Copyright: Copyright 2003 Gammon Software Solutions


About MUSHclient

This gives information about your copy of MUSHclient including the version number.

Version

This is the version number of this copy. Please mention it when reporting problems.

Credits...

Click to see details about people and companies that helped make MUSHclient what it is today.

License ...

Click to see the MUSHclient license agreement.

Web:

Click to open the MUSHclient web page.

Changes:

Click to see the release notes for MUSHclient.

See Also ...

Command

 About (Display program information, version number and copyright)

(Help topic: dialog=IDD_ABOUTBOX)


Activity window

This is the "activity list" window that shows all open worlds, and whether you have new activity in them.

You can click and drag the headings around to change the order of the columns.

Activating

You can activate any word in the list by double-clicking its line in the activity window.

In the case of the first 10 worlds you can activate (go to) any of the first 10 worlds by pressing Ctrl+N where N is the world number (eg. Ctrl+1 for world 1, Ctrl+2 for world 2, and so on up to Ctrl+0 for the 10th world).

You can also right-mouse-click on any world in the list and choose "switch to world" from the pop-up menu.

Seq

This is the internal sequence number of the world. It starts at 1 for the first world opened, and increases by 1 for each open world. You can determine the sequence in which worlds open by putting a list of worlds in the "worlds to open at startup" in the global configuration.

World

This is the internal world name, which you can alter from the first world configuration screen.

New

This shows the number of new lines received from that world since it was last active. If non-zero, then there is output that has arrived that you have not read yet.

Lines

This shows the number of lines that have arrived from that world.

Status

This shows the world status (eg. open, closed, connecting).

Since

This shows when you connected to the world.

Duration

This shows how long you have been connected to the world.

See Also ...

Topics

 Activity window

 Getting started

(Help topic: dialog=IDR_ACTIVITYTYPE)


Alias configuration (list)

Enable Aliases

If checked, all aliases are enabled (active).

Override with default aliases

If checked, next time the world is loaded your aliases are replaced with the default ones. See the help topic on "defaults" for more details.

Add...

Click to add an alias.

Edit...

Click to edit an existing alias.

Remove

Click to remove one or more selected aliases from the list.

Find...

Click to find an alias based on its contents.

Find Next

Click to repeat the next find (find another one that matches).

Load...

Click to load aliases from disk.

Save...

Click to save selected aliases to disk.

Move Up

Click to move the selected alias up the list (in other words, lower its sequence number).

Move Down

Click to move the selected alias down the list (in other words, raise its sequence number).

Copy

Click to copy the selected alias(es) to the clipboard in XML format.

Paste

Click to paste the clipboard into the alias list. The aliases must be in XML format (such as produced by the Copy button). Only aliases will be pasted, if there are other types on the clipboard.

Copy and paste is intended to allow you to get/put aliases onto the Forum, or exchange them between worlds or with other MUSHclient users.

Tree View

Check to show a "tree" view of the items. Leave unchecked to show a "list" view. In tree view only one item can be selected at once, however you can select an entire group for the purpose of copying the group to the clipboard, or deleting it.

In tree view items are sorted into groups. Inside the group the items are shown in sequence order.

Filter by:

Check to filter the visible items by the function "filter". Click on the button labelled "..." next to the "filter by" checkbox to enter the code for the scripted filter function. The filter function must be written in Lua and have a function named "filter" in the script, taking two arguments which are the name (label) of the alias, and a table of values corresponding to the various settings for it. For example, to show only aliases that do "send to script":

function filter (name, alias)

  return alias.send_to == sendto.script

end -- filter

You can use the various values for this alias to work out whether or not you want this particular one to be shown in the list (for example, if it sends to script). If the function returns the boolean value "false" then the item is not shown, otherwise it is shown in the list.

The filter script is saved in the world file, so you can use it again next time, however the filter flag is not remembered. You must explicitly enable it each time you want to filter the list.

The various fields in the alias table are documented here:

http://www.gammon.com.au/forum/?id=7123

In addition, some fields calculated at runtime are:

"execution_error"   // GetAliasInfo  (28) *

"execution_time"    // GetAliasInfo  (30) *

"included"          // GetAliasInfo  (15)

"invocation_count"  // GetAliasInfo  (10)

"last_match"        // GetAliasInfo  (25) *

"match_attempts"    // GetAliasInfo  (31) *

"match_count"       // GetAliasInfo  (24) *

"script_valid"      // GetAliasInfo  (27)

"temporary"         // GetAliasInfo  (14)

"times_matched"     // GetAliasInfo  (11)

"when_matched"      // GetAliasInfo  (13) *

Fields marked * may not be present (ie. be nil) under some circumstances (eg. regular expression failure).

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Command

 ConfigureAliases (Define aliases)

Dialog

 Edit alias

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: dialog=IDD_PREFS_P7)


ANSI Colour

Using the colours configuration screen you can completely customise the way that colours appear on the screen, in response to:

* ANSI colours sequences from the MUD; and

* Your selection of colours for triggered items, user input, and so on.

By clicking on one of the 16 colour buttons, you can adjust the actual colour that is displayed for a given colour "palette".

Colour swatches

Next to each colour button is a rectangular "swatch" which shows what the current setting for that colour is. By reviewing the swatches you can see your overall colour scheme. Click on any swatch to open the colour picker for that colour.

Colour Palette

To understand how the program handles colours, it is necessary to discuss the concept of a colour "palette". MUSHclient recognises 8 ANSI "normal" colours (black, red, green, yellow, blue, magenta, cyan and white), and the same 8 colours in "bold". The codes to change colours may be sent by a particular MUD if the appropriate function calls are made by a room designer. The normal colour is white text on a black background.

However, the actual colours that are displayed depend on the colour palette for a particular world. For example "black" might actually display as grey, and "white" might actually display as green.

Changing colours

To change the normal text colour click on "white" in the "normal" column (the button with "T" on it). You can then use the  colour selection dialog box to choose another colour. There are various ways of doing this...

The easiest way is to choose a colour from one of the "basic colours" on the left-hand side of the dialog box.

Or, you can move the mouse over the big coloured box on the right (holding down the mouse button) until the desired colour appears in the "Color/Solid" box.

Or, you can enter the actual "red/green/blue" or "hue/saturation/luminence" values in to the appropriately labelled boxes.

You cannot change colours if "override with default colours" (below) is checked.

Copying and pasting colours

You can right-mouse click on a colour swatch and select "copy", and then right-mouse click on another colour swatch and select "paste", to copy and paste colours from one swatch to another.

Lighter

There are three buttons labelled "lighter" on this screen. Two are under the "normal" and "bold" columns, and the third is on the right.

These let you quickly lighten the colours in the column (or in the case of the button on the right, all colours), so you can quickly adjust the "feel" of the colour scheme.

Darker

There are three buttons labelled "darker" on this screen. Two are under the "normal" and "bold" columns, and the third is on the right.

These let you quickly darken the colours in the column (or in the case of the button on the right, all colours), so you can quickly adjust the "feel" of the colour scheme.

Swap

Click on this to swap the bold and normal colours. You cannot swap colours if "override with default colours" (above) is checked.

ANSI colours...

Click on this button to reset all 16 colours to their ANSI defaults. This is useful if you want to see how the world would look to people with "standard" colours set up.

Load...

Click on this button to load a previously-saved set of colours. You can set up a colour scheme in one world, save it (using the "save" button) and then load the same colours into another world by using the "load" button.

You cannot load colours if "override with default colours" (above) is checked.

Save...

Click on this button to save your current set of 16 colours, plus your custom colours. You can then load them into another world if desired, so that each world has a consistent colour scheme.

More colour

Click on this button to increases the colour saturation of all of the ANSI colours, thus making them look "brighter".

Less colour

Click on this button to decrease the colour saturation of all of the ANSI colours, thus making them look "greyer".

Copy to custom...

Click on this button to copy all 16 colours to the 16 custom colours.

Invert

Click on this button to invert each colour (that is white becomes black, black becomes white and so on). Mathematically, each colour component is subtracted from 255 to give the new colour. eg. new_red = 255 - old_red

Random

Click on this to make all colours be chosen at random. You can also make individual colours random by clicking on its swatch to open the colour picker, and then clicking on the "random" button in the colour picker.

Use Custom Colour 16 as default

If checked, the default background colour is custom colour 16. If not checked, the default background colour is the colour selected for "normal black".

Override with default colours

If checked, the colour file specified with Defaults is used instead of the colours here, the next time the world is opened, or when Reload defaults is selected.

See Also ...

Command

 ConfigureColours (Sets output colours)

Dialog

 Custom Colour

(Help topic: dialog=IDD_PREFS_P5)


ASCII Art

This lets you generate large "text" letters using FIGLET - Frank, Ian and Glenn's LETters. FIGlet was written by Ian Chai, Glenn Gilford Chappell, John Cowan and Paul Burton, and is used with permission.

Text:

The text to be rendered in large letters.

Layout:

Type of spacing.

Font:

Font to use - various font files are supplied with MUSHclient, others are available over the Internet.

Browse...

Click to browse for a font file.

Insert

Click to insert the rendered text into your notepad document.

Cancel

See Also ...

Command

 ASCIIart (Generate ASCII art)

(Help topic: dialog=IDD_ASCII_ART)


Auto Say

Auto Say is a handy feature that lets you have lengthy conversations with another character (in the same room or another one) without having to type "say", "page", "whisper" or whatever each time you want to say something.

When auto-say is active (there is a button on the toolbar to activate/deactivate it, or you can type Shift+Ctrl+A to toggle auto-say on or off) then everything you type automatically has the "auto-say" prefix prepended to it.

For example, if you set the "auto-say" text to "say " (note the trailing space), then just type something in and "say " will be put in front of it.

You can set up certain exclusions to allow you to still move around and do other commands whilst auto-say is active.

Enable Auto Say

If this is checked, auto-say is active.

Use:

SHIFT+CTRL+A

to toggle auto-say on or off whilst playing a game, or click on the "auto-say" button on the toolbar.

Exclusions

Some things can be excluded from auto-say, so you can still walk around and do things while auto-say is active.

MUSHclient automatically turns auto-say off temporarily if the command starts with the auto-say sequence. For example, if auto-say is set to "say" and you type:

say hello

Then: "say hello" will be sent to the MUD, not "say say hello".

Also, using the numeric keypad to do things (eg. walk around) will bypass auto-say, so, for example, if you had keypad-8 programmed to send "north" and you hit it, then it would send "north", and not "say north".

Exclude commands starting with special characters

If this is checked then only lines starting with a letter or number (ie. A-Z, 0-9) are "auto-said". This means you can type things like "@teleport" without having to disable auto-say.

Exclude macros

If this is checked, then any command under the "macros" tab which is marked as "send now" or "replace", which matches the start of a line, is not auto-said. For example, if you have "examine" as a macro, then typing: "examine fred" will not be auto-said.

Override prefix:

You can type one or more characters here which, if they appear at the start of a line, disable auto-say for that line. For example, the default override prefix is "-", so if you typed:

-north

Then you would go north, not "say north".

Auto Say text:

Type here what you want to precede each "auto say" line. Remember to put in a trailing space, if that is what you want. For example, if you just had an auto-say text of "say", and then typed "hello", then "sayhello" would be sent to the world, probably causing an error. Therefore you should type in "say " (note the trailing space).

Suggested auto-say texts could be:

say

whisper person =

page person =

pose

+newbie

Send auto-say response to command interpreter (for aliases etc.)

If checked, the assembled auto-say strings is re-sent to the command interpreter, and thus could include aliases, speedwalks etc. For instance, you might have the auto-say text as "#chatall ". Since "#chatall" would be an alias from the Chat plugin you want it to be re-evaluated. In this case you would check this option.

See Also ...

Commands

 AutoSay (Whatever you type is "said" in the game)

 ConfigureAutosay (Sets auto-say options)

(Help topic: dialog=IDD_PREFS_P19)


Call chat user

Call another PC using the chat system.

TCP/IP Address:

Their address, either as a dotted decimal number (eg. 123.456.78.9) or a name, eg. theirdomain.com.

Port:

The port they are listening for calls on. Default is 4050.

Use zChat protocol

If checked, use the zChat protocol. If unchecked, use the MudMaster protocol.

If you are calling a zChat user, you may have more luck if checking this.

See Also ...

Topics

 Chat system

 Getting started

Command

 ChatSessions (Show all chat sessions for this world)

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_CHAT_CALL)


Chat

Our chat name:

The name that will appear on other peoples' chat sessions. It defauls to the character name you used in your "Connecting" configuration.

Automatically allow snoop

If checked, once you have authorised a chat user to snoop you, you are not prompted whether to allow a particular snoop session.

Incoming calls

If checked, allow incoming chat calls.

Accept incoming calls on port:

Which port to allow incoming chat calls on.

Validate caller

If checked, incoming calls are presented to you in a dialog box, where you are given the chance to accept or reject a particular call.

Message Appearance

How chat messages appear in your output window.

Messages in:

Chat messages foreground colour.

on

Chat messages background colour.

Ignore incoming colours

Discard colours on incoming chat calls. You might check this if other chat users are sending ANSI colour codes that clash with your own colour scheme.

Prefix messages with:

What to put at the start of each chat message, to distinguish it from other MUD output. For example, "(CHAT)".

Limits

This lets you limit incoming messages to the specified number of lines or bytes (for example, 100 lines, or 1000 bytes). You might set this is some chat users are sending annoyingly long messages.

Max. lines per message:

Incoming chat messages over this limit are truncated.

If zero, there is no limit on the number of lines.

Max. bytes per message:

Incoming chat messages over this limit are truncated.

If zero, there is no limit on the number of lines.

Automatically accept files

If checked, once you have authorised a chat user to send you files, you are not prompted whether to accept a particular file.

Save to:

Enter the directory for files to be saved to. If this is non-blank, and "automatically accept files" is checked, then incoming files can be received without any intervention. If this is blank, then you will be prompted for where to save incoming files.

Browse...

Browse for a directory to save incoming files to.

See Also ...

Topics

 Chat system

 Getting started

Command

 ConfigureChat (Configure chat settings)

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_PREFS_P23)


Chat details

Name:

This player's chat name.

Group:

You can place them into a group of your choice by entering a group name.

Actual IP address:

The TCP/IP address they connected from.

Call them on:

The TCP/IP address they suggest you call them on. You can click on this field and copy it.

Port:

The port number they suggest you call them on. You can click on this field and copy it.

ID:

The chat ID assigned by MUSHclient for this chat session.

Client:

The client they are using to connect to you.

Incoming

Checked if an incoming call.

Can snoop

Check to allow them to snoop you.

Can send us files

Check to allow them to send you files.

Private

Check to mark them as private, so other people cannot see they are connected to you.

Ignore

Check to ignore them.

Can send us commands

Check to allow them to send you commands.

See Also ...

Topics

 Chat system

 Getting started

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_CHAT_DETAILS)


Chat sessions

Lists current chat sessions. The list will automatically refresh if new sessions are started, or old ones dropped, while you are looking at it.

Status

Shows whether or not you are accepting calls (inwards).

New Call...

Click to place a new call (outwards).

Close

Click to close this window.

Edit...

Click to edit the selected call (change options etc.).

Ping

Click to ping the selected call(s).

Snoop

Click to snoop the selected call(s).

Send File...

Click to send a file to the selected call.

Hang Up

Click to hang up the selected call(s).

Chat...

Click to send a chat message to the selected call(s).

Emote...

Click to emote a chat message to the selected call(s).

Peek Connections

Click to peek the connections of the selected call(s).

Request Connections

Click to request the connections of the selected call(s). (Requesting a connection means you try to connect to the people they are connected to).

Chat All...

Click to chat to all connected calls.

Emote All...

Click to emote to all connected calls.

See Also ...

Topics

 Chat system

 Getting started

Command

 ChatSessions (Show all chat sessions for this world)

Dialog

 Chat details

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_CHAT_LIST)


Chat to all

This sends a "say" to the selected users.

Say:

What to say to the selected chat users.

See Also ...

Topics

 Chat system

 Getting started

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_CHAT_SAY_ALL)


Check Spelling

Consider Changing:

Suggestions:

Ignore

Ignore All

Add

Change

Change All

Suggest

Undo

Options...

Dictionaries...

Help...

Add words to:

Cancel

(Help topic: dialog=CHECKSPELLINGDLG)


Choose from combo-box

General input box for use by scripting.

This appears when a script calls: utils.choose

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_LUA_CHOOSE)


Choose from list box

General input box for use by scripting.

This appears when a script calls: utils.listbox

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_LUA_CHOOSE_LIST)


Choose notepad window

This dialog appears if you choose "Edit ... Notepad" and the world already has related notepad windows.

New

Create a new notepad window.

Open existing

Use the selected existing notepad window.

Cancel

Do not open any notepad window.

See Also ...

Topic

 Notepad

Command

 NotesWorkArea (Opens a notepad window for working on long commands etc.)

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: dialog=IDD_CHOOSE_NOTEPAD)


Colour picker

This dialog box provides a handy colour picker, to help choose colours for triggers, scripting, MXP programming, and generally throughout the program.

Colour list

This shows all of the internal colours, sorted into various sequences (controlled by the Sort combo-box). The default is Hue, which groups related colours (eg. the reds come together).

Underneath that is the currently-selected colour's name, which you can click on to copy it to the clipboard, and close the colour picker dialog box. If this box is blank, then the current colour does not have a matching name.

Select a colour in the list by clicking on the colour name or the colour swatch.

Colour buttons

If you click on any of the buttons mentioned below, it will copy the value to the clipboard, and then close the colour picker. This lets you choose a colour, and have it copied to the clipboard in the format of your choice, in one click.

MXP:

This is the selected colour code in MXP/HTML format (eg. for use in an MXP-enabled MUD, or on a web page). eg. #E9967A

VB:

This is the selected colour code in Visual Basic hex format (eg. for use in a VBscript program).  eg. &h7A96E9

JScript:

This is the selected colour code in C format (eg. for use in a C program, Perlscript or Jscript). eg. 0x7A96E9

Lua:

This is the selected colour code as a straight decimal number (eg. for use in a Lua program, or any program that does not support hex codes). eg. 8034025

Colour sliders

The three colour sliders (red/green/blue) can be moved by clicking and dragging, which will change the component of the selected colour.

Also, once the slider is selected you can use the arrow keys to increase/decrease the component by one. Pressing PageUp or PageDown to increase/decrease the component by ten.

As you move the sliders the colour swatch will be updated to show the new colour. Also the colour codes in the various windows will also be updated. If the new colour matches a known colour name that will appear in the "Name" box.

Red:

The red component of the selected colour, in the range 0 to 255.

Green:

The green component of the selected colour, in the range 0 to 255.

Blue:

The blue component of the selected colour, in the range 0 to 255.

Hue:

The hue component of the selected colour.

Saturation:

The saturation component of the selected colour.

Luminance:

The saturation component of the selected colour.

Sort:

The sequence for sorting the colours in the colour list.

Colour swatch

The colour swatch shows the currently-selected colour.

Click on it to open the Windows colour picker. You can use the Windows colour picker to adjust the luminance (with the slider bar), the saturation (by clicking further up or down in the colour window), or the hue (by clicking further left or right in the colour window).

OK

Select the colour of your choice, and close the dialog box (this is the default action if you press Enter).

Random

Change the colour to one chosen at random.

Other colour...

Open the standard Windows colour picker for further colour selection. As described above you can use this to change the luminance, saturation and hue of the selected colour.

Paste

If there is a valid MXP/HTML/VB/C/Lua colour on the clipboard, this button will be active. Clicking it will paste the colour code into the window, and the various boxes will adjust accordingly.

Close

Close the colour picker without selecting a colour. This is the action that occurs if you press Escape.

See Also ...

Topics

 Scripting

 Utilities

Command

 ColourPicker (Choose a colour from a list)

Dialog

 ANSI Colour

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_COLOUR_PICKER)


Command history

Shows the previous commands you have entered so you can recall or copy one.

Recall

Recalls the selected command into the command window. You can then edit it before sending it to the MUD.

Do

Does the selected command (sends it immediately). The command history window remains open so you can select another command afterwards.

Notepad...

Opens a notepad window with the selected command in it.

Find...

Finds a command. If you have a lot of commands in this window this would be a handy way of finding a particular one.

Find Next

Finds the next command that matches the previous find string.

See Also ...

Command

 CommandHistory (Shows previous commands entered)

(Help topic: dialog=IDD_COMMAND_HISTORY)


Commands

Echo My Input In (colour):

If you enable "echo my input" then commands you type (and transmit) are echoed in the output buffer (top part of the screen) after being processed for speed walking, macros (function keys), aliases, and command stacking. You will also see commands which have been automatically transmitted because they matched a trigger. You can choose the colour they appear in (from the custom colours).

This is very handy for keeping an eye on triggers, and what is actually sent after macros etc. are evaluated.

Speed Walking

This lets you configure speed-walking, which is a shorthand way of moving around (eg. 5S moves you South 5 times). See the description for "speed walking" for more details.

Enable Speed Walking, prefix is:

If checked, speed walking is enabled. You must specify a speed-walk prefix string which indicates to MUSHclient that what follows is a speedwalk (eg. "#").

Filler:

Some MUDs do not like length identical strings. You can specify a speedwalk "filler" which can be an innocous word like "look" which is sent whenever the letter "F" (for filler) appears in the speedwalk string.

Delay:

Some MUDs can not handle speedwalks sent at high speed. You can specify a delay in millisconds (thousandths of a second) which will be placed between each speedwalk direction. For instance, 500 would be 1/2 a second.

Command Stacking

Command-stacking lets you combine commands on a single line, for ease of typing, and to make it easier to recall them. For example:

open bag; get food; eat food; close bag

If checked, command stacking is enabled.

If command stacking is enabled you can use the command stack character inside a line by doubling it. That is, if the command stack character is ";" then entering ";;" will be converted to a single ";".

You can temporarily disable command stacking for a line by entering the command stack character as the very first character. For example, if the command stack character is ";" then entering ";say go west; then east" will be treated as a single line.

Command Stacking Using:

Specify the command-stack character here. It must be a single character (eg. ";" or "|").

Command Colours

Click on the colour swatches to specify the text colour, and background colour, for displaying commands. This is the colour used in the command window (the lower window), not the colour commands are echoed in the output window. To change the colour commands are echoed in, see "Echo My Input In (colour)" above.

Tab Completion...

Tab completion is a feature that lets you type a partial word, and then press [tab] to have MUSHclient complete the word from recent MUD output.

For example, if you received a message:

Gandalf tells you, hi there

You might type:

tell Gan[tab]

MUSHclient will scan backwards and find that "Gandalf" matches "Gan" and complete it for you. The number of lines it scans can be set by clicking on the "Tab Completion" button.

You can also specify a list of words that are to be searched, even if they did not arrive recently. To do this click the "Tab Completion" button and edit that list.

Keyboard preferences...

Click to edit various other command preferences that would not fit on the main commands configuration screen.

Auto-repeat Command

With this option checked, every time you press <enter> to transmit a command to the MUD, the command is retained (repeated) in the input window, but selected (highlighted). You can then press <enter> to send it again, or just start typing to replace it.

Tab Completion In Lower Case

With this option checked, when you press [tab] to auto-complete the word you are currently typing, it will be completed in all lower-case, otherwise the capitalisation of the word as it appears in the output buffer will be used.

Translate German characters

With this option checked, various German characters will be expanded out into normal ASCII characters when text is sent to the MUD. Translation takes place at send time, not command input.

Spell Check On Send

If checked, every time you send a command it will be spell-checked. The spell-checker must be enabled using the File Menu -> Global Preferences -> General -> Spell check -> Enable, otherwise this option will be greyed-out.

Translate Backslash Sequences

With this option checked, you can enter Escape sequences into your commands, to process characters you cannot normally type (such as the "bell" character).

Escape sequences can be used in various places to represent non-printable or special characters.

The sequences are:

\a Bell (alert)

\b Backspace

\f Formfeed

\n New line

\r Carriage return

\t Horizontal tab

\v Vertical tab

\' Single quotation mark

\" Double quotation mark

\\ Backslash

\? Literal question mark

\xhh  ASCII character in hexadecimal notation

eg.

say warning \a\a

(this would say "warning" followed by two "bell" characters)

Keep Commands On Prompt Line

If checked, commands are kept on the same line as previous MUD output, if it was not terminated by a newline. For example:

If checked:

<1000/1000 hp 100/100 m 750/750 mv> north

If not checked:

<1000/1000 hp 100/100 m 750/750 mv>

north

Ignore 'Echo Off' messages

Some MUDs will send the "echo off" telnet sequence to turn off command echoing (for example, before requesting a password). If for some reason this keeps command echoing suppressed you can check this option.

Spam prevention

Spam prevention is a feature that stops you inadvertently spamming the MUD, and being disconnected, by sending the same command many times. For example, some MUDs might not allow 20 identical commands. By using this feature, MUSHclient will detect if you send the same command many times, and insert a "spam breaker" command automatically. For example, during a fight you might type "punch" many times.

Enable Spam Prevention

Check to enable the spam prevention feature.

Every X identical commands

Enter the number of commands to allow through before sending the spam breaker (eg. 20).

Send

Enter the spam breaking word. This should be something that is harmless (like "score", "look", "who", "inventory") but not something you are likely to be typing often in a sequence.

Font

You can choose what font is used in the command window.

Change Font...

Click to change the command window font.

Override With Default

If checked, the default font specified in Defaults will be used instead of the font here, next time the world is opened, or as soon as you select Reload defaults.

Command History

You can choose how many lines are retained in the "history" window.

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

 Speed walking

Command

 ConfigureCommands (Sets input options)

Dialog

 Keyboard preferences

Functions

 EvaluateSpeedwalk (Evaluates a speed walk string)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 ReverseSpeedwalk (Reverses a speed walk string)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: dialog=IDD_PREFS_P9)


Complete Function Name

This dialog box lets you choose a function name from a list which matches what you have partially typed.

Select the function you want and press <Enter> to accept it, or <Escape> to cancel.

If the list is empty that means no inbuilt function matched the selection.

See Also ...

Topic

 Notepad

Command

 CompleteFunction (Invokes a menu of function names that match a partially typed one)

Dialog

 Functions

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: dialog=IDD_COMPLETE_WORD)


Configure numeric keypad

Use this dialog to configure what is sent if you press one of the numeric keypad keys. The string you enter is sent through command processing so you can put aliases here.

Enable Keypad Keys

If checked, the configured strings are sent.

If not checked, the numbers on the keys are sent (eg. key "2" would be "2").

Show Contents If CTRL Held Down

If checked, you see what is sent if the Ctrl key is held down (eg. Ctrl+2).

If unchecked, you see what is sent if the Ctrl key is not held down.

Hint

To do more elaborate things (like expanding variables, running scripts) enter a nonsense word as what to send, and then make an alias to "catch" that word, and do the extra processing in the alias. One way of doing this is to use the Edit -> Generate Unique ID menu item to generate a unique word, like this:

381e051a828fb201b6914699

This is unlikely to be something you would normally want to type into the MUD. Then make an alias to match on "381e051a828fb201b6914699" (or whatever word you choose) and make the alias do things like expand variables, call scripts, etc.

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Commands

 ConfigureKeypad (Sets numeric keypad options)

 CtrlKeypad0 (Executes a user-defined numeric keypad action.)

 CtrlKeypad1 (Executes a user-defined numeric keypad action.)

 CtrlKeypad2 (Executes a user-defined numeric keypad action.)

 CtrlKeypad3 (Executes a user-defined numeric keypad action.)

 CtrlKeypad4 (Executes a user-defined numeric keypad action.)

 CtrlKeypad5 (Executes a user-defined numeric keypad action.)

 CtrlKeypad6 (Executes a user-defined numeric keypad action.)

 CtrlKeypad7 (Executes a user-defined numeric keypad action.)

 CtrlKeypad8 (Executes a user-defined numeric keypad action.)

 CtrlKeypad9 (Executes a user-defined numeric keypad action.)

 CtrlKeypadDash (Executes a user-defined numeric keypad action.)

 CtrlKeypadDot (Executes a user-defined numeric keypad action.)

 CtrlKeypadPlus (Executes a user-defined numeric keypad action.)

 CtrlKeypadSlash (Executes a user-defined numeric keypad action.)

 CtrlKeypadStar (Executes a user-defined numeric keypad action.)

 Keypad0 (Executes a user-defined numeric keypad action.)

 Keypad1 (Executes a user-defined numeric keypad action.)

 Keypad2 (Executes a user-defined numeric keypad action.)

 Keypad3 (Executes a user-defined numeric keypad action.)

 Keypad4 (Executes a user-defined numeric keypad action.)

 Keypad5 (Executes a user-defined numeric keypad action.)

 Keypad6 (Executes a user-defined numeric keypad action.)

 Keypad7 (Executes a user-defined numeric keypad action.)

 Keypad8 (Executes a user-defined numeric keypad action.)

 Keypad9 (Executes a user-defined numeric keypad action.)

 KeypadDash (Executes a user-defined numeric keypad action.)

 KeypadDot (Executes a user-defined numeric keypad action.)

 KeypadPlus (Executes a user-defined numeric keypad action.)

 KeypadSlash (Executes a user-defined numeric keypad action.)

 KeypadStar (Executes a user-defined numeric keypad action.)

Dialog

 Generate Unique ID

(Help topic: dialog=IDD_PREFS_P12)


Confirm preamble and postamble for pasting or sending file to the world

This dialog lets you confirm the preamble and postamble for pasting or sending data to a world.

1. Send this at the start:

This text is sent at the start of the whole operation.

2. Send this at the start of each line:

This text is sent at the start of each line.

3. Send this at the end of each line:

This text is sent at the end of each line.

4. Send this at the end:

This text is sent at the end of the whole operation.

Delay between lines:

Enter the delay in milliseconds between pasting or sending each line.

Every X lines.

If you only need the delay (say) every 100 lines, enter the number of lines here to be sent without a delay.

Commented softcode

If checked, the text is assumed to be commented softcode, and the comments are removed.

Echo each line to output window

If checked, each line is echoed to the output window.

See Also ...

Command

 PasteToMush (Sends the contents of the clipboard directly to the current world)

Dialog

 Paste

(Help topic: dialog=IDD_PASTE_PREAMBLES)


Connecting

Character name and password

In order to automatically connect to your MUD, you can enter your character name and password below.

Name:

Your character's name.

Password:

Your character's password. If you leave it blank you will be prompted with a dialog box every time you connect to the world.

Connect:

Connect method:

* No auto-connect - character name and password are not sent.

* MUSH/MOO method - sends the command: CONNECT name password

* Diku style - sends: name (newline) password (newline)

* MXP - uses MXP tags to send the name and password when requested

Connect Text. (Sent after connected):

Something to send to the world immediately after connecting (eg. "WHO").

You can use %name% or %password% if you wish the name or password supplied above to be inserted. You can use this for unusual connection methods. For example, to do a MUSH-style connect using the "connect text" box you could enter:

connect %name% %password%

See Also ...

Command

 ConfigureNameAndPassword (Sets character name and password)

Dialog

 Logging

(Help topic: dialog=IDD_PREFS_P21)


Credits

Shows credits for the many people and companies who have helped make MUSHclient the program it is today!

See Also ...

Dialog

 About MUSHclient

(Help topic: dialog=IDD_CREDITS)


Custom Colour

Use this screen to define 16 custom colours, which are used for highlighting lines that match triggers, and for colouring "notes" from scripts, and when commands are echoed in the output window.

Each of the 16 colours can have a "foreground" (ie. Text) and "background" colour specified.

You can also give each colour a name - this shows up in the custom colour combo boxes in other configuration dialogs (eg. triggers) so you can remind yourself of what each colour is for. eg. you might have custom colour 1 as white on red and label it "enemies".

Colour swatches

Next to each colour button is a rectangular "swatch" which shows what the current setting for that colour is. By reviewing the swatches you can see your overall colour scheme. You can click on the colour swatches to open the colour picker.

Changing colours

To change a colour click on the colour swatch, and then choose another colour by using the colour picker. You can move the slider bars, choose from a list, or open the Windows colour picker.

Copying and pasting colours

You can right-mouse click on a colour swatch and select "copy", and then right-mouse click on another colour swatch and select "paste", to copy and paste colours from one swatch to another.

ANSI colours for this world

This shows the current ANSI colours you have set up, so you can compare the custom colours to them.

Invert

Click on this button to invert each colour (that is white becomes black, black becomes white and so on). Mathematically, each colour component is subtracted from 255 to give the new colour. eg. new_colour = 255 - old_colour

Lighter

Click on this button to lighten all of the colours.

Darker

Click on this button to darken all of the colours.

More colour

Click on this button to increases the colour saturation of all of the colours, thus making them look "brighter".

Less colour

Click on this button to decrease the colour saturation of all of the colours, thus making them look "greyer".

Defaults

Click on this to return all custom colours to the MUSHclient defaults.

Random

Click on this to make all colours be chosen at random. Hint - you can make individual colours random by clicking on them to open the colour picker, and then clicking on the "random" button in the colour picker.

Swap

Click on this to swap the foreground and background colour for each custom colour.

See Also ...

Command

 ConfigureCustomColours (Custom Colours)

Dialog

 ANSI Colour

(Help topic: dialog=IDD_PREFS_P3)


Debug

This dialog is invoked by calling debug.debug () from within a Lua script.

You can use it to inspect variables, do a traceback, enter debugging commands, or abort the script.

Source

The short form of the source of this script. If loaded from a file it will be the filename preceded by the "@" symbol.

First, last lines

If known, the first and last line numbers in which the current function was defined.

Current line

The line number inside the script at which the debug.debug () command resides.

What function is

This will be one of:

•	Lua - a regular Lua function

•	main - inside the main Lua chunk (that is, not inside a function)

•	C - a C function

Name

If it can be determined, the name of the current function, followed by what the name is in brackets. (eg. "myfunction (local)" ).

Function

The function address.

Number of upvalues

How many upvalues this function has.

Show upvalues

Clicking this runs a small script to display the upvalues of the current function, if any, in the output window. The script looks like this:

do

local i, name, val = 1

local t = debug.getinfo (3, 'f')

local f = t.func

-- keep going until we run out of values

repeat

  name, val = debug.getupvalue (f, i)

  if name then

    ColourNote ('limegreen', 'black', name .. ' = ' .. tostring (val))

    i = i + 1

  end

until not name

ColourNote ('limegreen', 'black', tostring (i - 1) .. ' upvalue(s)')

end -- of local block

Show locals

Clicking this runs a small script to display the local variables of the current function, if any, in the output window. The script looks like this:

do local i, name, val = 1

repeat

 name, val = debug.getlocal (3, i)

  if name then

    ColourNote ('limegreen', 'black', name .. ' = ' .. tostring (val))

    i = i + 1

  end

until not name

ColourNote ('limegreen', 'black', tostring (i - 1) .. ' local(s)')

end -- local block

Traceback

Clicking this runs a small script do display the traceback information, namely:

ColourNote ('limegreen', 'black', debug.traceback ())

Command

You can type Lua commands into this window and press <Enter> (or click on Do Command). The command you entered is sent to the Lua interpreter to be executed in the context of the current script. For example, you could print or change global variables. The current command is remembered from one debug session to the next.

Edit...

Click this to edit the current contents of the command window in a larger dialog box. This larger box has access to function help, and function-name completion.

Do command

Sends the contents of the "command" box to the Lua interpreter.

Continue execution

Lets the script that called debug.debug () continue executing. Pressing <Esc> to dismiss the dialog has the same effect.

Abort script

Aborts the calling script with the error "Script aborted".

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Scripts

(Help topic: dialog=IDD_LUA_DEBUG)


Debug simulated world input

Use this for debugging things like triggers. You can enter text here and MUSHclient will think it has arrived from the world. You can imbed hex codes (like colour codes) by using backslashes.

Specials

To simplify entering special codes (like bold text, red background, MXP codes and so on) you can select them from the combo-box, and then click the "Insert" button to have the selected codes pasted at the current selection point.

Insert special

Click to insert the selected special codes (shown in hex in the adjacent combo-box) at the insertion point in the main text box.

Insert Unicode

Click to insert a Unicode character code (eg. 060C) as the equivalent UTF-8 codes. This is for simulating Unicode (UTF-8) input arriving from the MUD. Depending on the code entered up to 6 bytes (hex sequences preceded by a backslash) may be entered into the input window.

Text to simulate arriving from the world:

This is the text that is processed by MUSHclient as if it had been received from the current world.

See Also ...

Command

 DebugWorldInput (Debug world input)

Dialog

 Insert Unicode Character

(Help topic: dialog=IDD_DEBUG_INPUT)


Dictionaries

Words:

Action:

Other word:

Add Word

Delete Word

Import...

Export...

Files:

Add File

New File...

Remove File

Help

Close

Language:

(Help topic: dialog=EDITLEXDLG)


Edit

General-purpose dialog for editing text (like trigger/alias match/send text).

This is used for single-line input.

->

This button is visible if you are editing a regular expression. It invokes a menu of helpful regular expression "insertions" that you can choose. For example, if you want to match on a letter you can click on this button, then choose Character Class -> Letter, and the appropriate regular expression will be inserted at the cursor position.

Also, the final entry "Help..." in the menu invokes the Regular Expression help page.

(Help topic: dialog=IDD_EDIT)


Edit alias

Alias:

What to match on. Can be a regular expression. If not a regular expression, use "*" to match on wildcards (variable text).

For example, "kick *" would match on "kick (someone)".

If you are using regular expressions wildcards are things in brackets.

For example: "^kick (.*)$" would be the same as the above, with the wildcard being the expression in round brackets.

(...)

Click on the button labelled "..." to open a larger box for editing the alias match text.

Send:

What to send if the alias matches. You can use %1 to match the first wildcard, %2 to match the second wildcard, and so on up to %9. For wildcards above 9 you can use %<n> (for example, %<50> for wildcard 50).

%0 represents the whole matching text.

Use %% to represent a single % symbol. You can also use %C to insert the contents of the Clipboard, and %N to insert the current alias's name (label).

If you are sending to script then any quotes or other special characters in the send text (inside the wildcard contents) are "escaped" appropriately for the script language you are using.

For example, if you were sending to Jscript, and %1 contained 'Nick said "hello" ', and the "send" text was:

world.Note "%1"

In this case it would parse the line:

world.Note "Nick said \"hello\" "

(...)

Click on the button labelled "..." to open a larger box for editing the alias send text.

Alternatively press Alt+Enter to open the editing dialog box.

Enabled

If checked, the alias is enabled (active).

Omit From Log File

If checked, the alias is not logged.

Ignore Case

If checked, the alias is not case-sensitive. Otherwise "AB" is considered different from "ab".

Regular Expression

If checked, the alias is a regular expression. See the regular expression documentation for more details.

Expand Variables

If checked, variables in the alias "send" text are expanded. A variable starts with "@" and is followed by the variable name. To put "@" in the alias response, use "@@".

For example, if the variable "target" contained "kobold", then sending "punch @target" would send "punch kobold".

Omit From Output

If checked, the alias response is not echoed in the output window.

Temporary

If checked, the alias is not saved in the world file.

One-shot

If checked, once this alias fires, it is deleted.

Keep Evaluating

If checked, the further aliases are checked against the same thing you typed. This lets you set one alias to (say) omit things from the log file, and other aliases to do different things.

Echo Alias

If checked, the alias itself is echoed in the output window.

Omit From Command History

If checked, the alias itself is not stored in the command history.

Send To:

Where to send the alias response to. The default is to the MUD. However you can choose other places, such as the output window, a notepad window, or make the alias "send to script" in which case the alias "send" text can be script commands.

If you send to "execute" then the send text is re-evaluated through the command processor, so you can then have an alias inside an alias if you want.

The "send-to" box lets you choose to send the "send" text to one of:

•	 world (the MUD)

•	 command (the command window)

•	 output (directly to the output window, as a note to yourself)

•	 status (to the status line)

•	 notepad - new (create a new notepad window)

•	 notepad - append (append to a notepad window)

•	 log file (directly to the log file)

•	 notepad - replace (replace an existing notepad window)

•	 world - speedwalk delay (queue for delayed send at the speedwalk rate)

•	 variable (set a variable, whose name you provide in the variable box)

•	 execute (execute through normal command parser, so aliases, speedwalks etc. will be executed)

•	 speedwalk (send to world after converting speedwalk string)

•	 script (execute as a script command in the current scripting language)

•	 world - immediate (to the MUD immediately, even if you are speedwalking)

Sequence:

Aliases are evaluated in sequence number order, where the lower number is evaluated sooner. Change this number to alter the order of alias evaluation.

Reverse Speedwalk

If the alias is "send to speedwalk" this button will be active. Clicking it will reverse the speedwalk direction. (eg. 4n 5e would become 5w 4s).

Convert to Regular Expression

Click this button to convert a "normal" alias to a regular expression. This is a quick way of converting an alias into a regular expression ready for improving on it.

Label:

Aliases can have names - put the name in the "label" box.

Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

•	 Start with a letter (A-Z)

•	 Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Menu

If checked, the alias is added to the menu which appears when you Control-Left-Click in the output or command window. This lets you set up a menu of things you do frequently.

The menu text is the label, with underscore replaced by spaces.

Script:

If you have a script file, the alias will call a script in it if you place the script function name here. The script function must be declared with 3 arguments: name, line, wildcards. For example, in VBscript:

sub my_alias_function (name, line, wildcards)

  world.note "alias " & name & " called."

end sub

However in Lua all arguments are optional (as is usual with Lua function calls).

Group:

Aliases can be placed in groups. If you want to group your aliases place the group name in the group box. You can use groups to enable/disable or delete groups of aliases.

Variable:

If you have set the alias to "send to variable", place the variable name here.

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Dialog

 Alias configuration (list)

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: dialog=IDD_EDIT_ALIAS)


Edit macro

Macro type:

The key that you press to invoke this macro.

Send:

What to send. This gets sent through the command processor, so it can consist of aliases, speedwalks or script commands.

Send action

What to do with the send text when you press the macro key.

Replace

The entire contents of the command window is replaced by the macro.

Send Now

The macro is immediately acted upon, however the command window contents are not changed.

Insert

The macro contents is inserted into the command window. You can then edit it if you wish.

Hint

To do more elaborate things (like expanding variables, running scripts) enter a nonsense word in the "send" box, and then make an alias to "catch" that word, and do the extra processing in the alias. One way of doing this is to use the Edit -> Generate Unique ID menu item to generate a unique word, like this:

381e051a828fb201b6914699

This is unlikely to be something you would normally want to type into the MUD. Then make an alias to match on "381e051a828fb201b6914699" (or whatever word you choose) and make the alias do things like expand variables, call scripts, etc.

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Command

 ConfigureMacros (Sets macro options)

Dialog

 Generate Unique ID

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: dialog=IDD_EDIT_MACRO)


Edit timer

Every interval:

For timers that fire at intervals (eg. every 5 minutes), fill in the next 6 boxes as required.

hour

How many hours apart.

minute

How many minutes apart.

second

How many seconds apart.

Offset:

The offset is used to make a timer fire a fixed amount before its interval elapses. This is useful to "stagger" timed events. For example, if you wanted to have your character:

pose looks around vaguely

every 2 minutes, and

pose scratches his head

every 2 minutes (but in-between the other "pose") then you would set both timers to go off at 2 minute intervals, but have one of them have a 1 minute offset. If you didnï¿½t do that then both timers would go off every 2 minutes, displaying both messages in quick succession.

hour

Offset in hours.

minute

Offset in minutes.

second

Offset in seconds.

At the time:

Click on this to have a timer fire at a particular time of the day (using a 24-hour clock). This sort of timer will then fire at that time, every day.

hour

Hour to fire.

minute

Minute to fire.

second

Second to fire.

Send:

What to send when the timer fires.

(...)

Click on the button labelled "..." to open a larger box for editing the timer send text.

Alternatively press Alt+Enter to open the editing dialog box.

Only Fire Once

If checked, the timer only fires once, and then deletes itself.

Temporary

If checked, the timer is not saved in the world file.

Active When Disconnected

If checked, the timer will fire even if the world is not connected. This lets you make a "reconnect" timer, for example.

Send To:

Where to send the timer send text to. The default is to the MUD. However you can choose other places, such as the output window, a notepad window, or make the timer "send to script" in which case the timer "send" text can be script commands.

If you send to "execute" then the send text is evaluated through the command processor, so you can then have an alias inside a timer if you want.

The "send-to" box lets you choose to send the "send" text to one of:

•	 world (the MUD)

•	 command (the command window)

•	 output (directly to the output window, as a note to yourself)

•	 status (to the status line)

•	 notepad - new (create a new notepad window)

•	 notepad - append (append to a notepad window)

•	 log file (directly to the log file)

•	 notepad - replace (replace an existing notepad window)

•	 world - speedwalk delay (queue for delayed send at the speedwalk rate)

•	 variable (set a variable, whose name you provide in the variable box)

•	 execute (execute through normal command parser, so aliases, speedwalks etc. will be executed)

•	 speedwalk (send to world after converting speedwalk string)

•	 script (execute as a script command in the current scripting language)

•	 world - immediate (to the MUD immediately, even if you are speedwalking)

Variable:

If you have set the timer to "send to variable", place the variable name here.

Label:

Timers can have names - put the name in the "label" box.

Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

•	 Start with a letter (A-Z)

•	 Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Enabled

If checked, the timer is enabled (active).

Script:

If you have a script file, the timer will call a script in it if you place the script function name here. The script function must be declared with one argument: the timer name. For example, in VBscript:

sub my_timer_function (name)

 world.note "timer " & name & " called."

end sub

However in Lua all arguments are optional (as is usual with Lua function calls).

Group:

Timers can be placed in groups. If you want to group your timers place the group name in the group box. You can use groups to enable/disable or delete groups of timers.

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Command

 ConfigureTimers (Define timers)

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: dialog=IDD_EDIT_TIMER)


Edit trigger

When a trigger matches MUSHclient does not evaluate any further triggers (unless "Keep Evaluating" is checked). Thus a trigger can be used as a "blocker" to stop further triggers down the list from being processed. Triggers with lower sequence numbers are evaluated before triggers with higher sequence numbers. Thus, use sequence numbers to control the evaluating sequence. Triggers with the same sequence number are evaluated in an undefined order.

Trigger:

This is the text that you are expecting from the MUD. If it is matched on exactly, then the text in the "send" box is acted upon and your script (if any) is called.

(...)

Click to edit the trigger text in a larger window. If the trigger is a regular expression the larger window also has an extra "helper" button to assist you in adding regular expression items.

Match: (colour) on (colour)

You can make a trigger match a particular colour line by setting these options. Leave the colours at "(any)" to match on any colour. You can also match on a line in bold/italic/inverse or any combination of these. These check-boxes are "tri-state", which means they can be:

1. Unchecked (the line must not be bold, for example)

2. Checked (the line must be bold, for example)

3. Greyed out (it doesn't matter if the line is bold or not)

The first character of the matching text is  checked for the specified colour.

Bold

Check to match if the first character of the matching text is bold. Uncheck if the first character must not be bold. Greyed out if you don't care.

Italic

Check to match if the first character of the matching text is italic. Uncheck if the first character must not be italic. Greyed out if you don't care.

Inverse

Check to match if the first character of the matching text is inverse. Uncheck if the first character must not be inverse. Greyed out if you don't care.

Send:

What to send to the "send" destination. The default send destination is back to the MUD.

You can use %1 to match the first wildcard, %2 to match the second wildcard, and so on up to %9. For wildcards above 9 you can use %<n> (for example, %<50> for wildcard 50).

For named wildcards you can use %<name> (for example, %<mob> for a wildcard with the name "mob"). Named wildcards are produced by using a regular expression and a group like: (?P<mob>.+?)

%0 represents the whole matching text.

Use %% to represent a single % symbol. You can also use %C to insert the contents of the Clipboard, and %N to insert the current trigger's name (label).

If you are sending to script then any quotes or other special characters in the send text (inside the wildcard contents) are "escaped" appropriately for the script language you are using.

(...)

Click to edit the send text in a larger box.

Alternatively press Alt+Enter to open the editing dialog box.

Enabled

If checked, the trigger is enabled (active).

Ignore case

If checked, the trigger match is case insensitive. If not checked, the "case" of the matching text must agree exactly.

Omit from log file

If checked, the matching line is not logged to the log file (if open).

Omit from output

If checked, the matching line is omitted from the output window.

Keep evaluating

If checked, the same line is checked against further triggers. If unchecked the first matching trigger cancels trigger evaluation. You can change the order in which triggers are evaluated by amending the sequence field.

Regular expression

If checked, the trigger match text is a regular expression. See "regular expressions" in the help for more information. You can convert an "ordinary" trigger to a regular expression by clicking the "Convert to Regular Expression" box. Then you can edit the regular expression to customise it.

Repeat on same line

If checked, the trigger is matched repeatedly against the same line (this only applies to regular expressions). This lets you colour individual words which might appear more than once on a line.

Expand variables

If expand variables is on (checked) then a variable name in the format @name is expanded. To put a @ symbol itself in the trigger, use two @@.

Here is an example of such an trigger:

unlock @direction

For this trigger to work you would need a variables, "direction".

You can set variables by using the configuration dialog box, or through a scripting command (if scripting is enabled), like this:

/SetVariable ("direction", "north")

If you want to use variables inside regular expressions and not have special characters "fixed" by putting backslashes inside them, use the syntax:

@!variable

Temporary

If checked, the trigger will not be saved to the world file. In other words, it is a temporary one only for use in this session.

Multi-line, match ... lines.

If checked, this trigger will match multiple lines, starting with the current line (the most recently received), and including the number of lines specified in the adjacent box.

For multi-line triggers MUSHclient assembles a "block of text" which is the specified number of lines, working backwards from the current line, each one ending with a newline character (assembled in the order in which they arrived, of course). This text block is then passed to the regular expression handler to see if it matches. The number of lines is lines with a newline at the end of the, not necessarily the number of lines you see on the screen. For instance, if the MUD sent some 200-character lines that line-wrapped, each line is counted as one line, even if you see four lines on the screen.

A simple example would be to match on:

You are hungry.

You are thirsty.

To match this you might have the regular expression:

Match: ^You are hungry\.\nYou are thirsty\.\n\z

The \n represents the "newline" character (hex 0A) between the two lines, the \. is a single period (at the end of the sentences) and the \z is an "anchor" to the end of the text block. The \z is not really necessary for this example, but could be useful for longer ones.

For this example the "number of lines" would be 2, as you are trying to match a 2-line block.

A more complex example is to match your inventory, which might be:

You are carrying:

     a magic mushroom

     a torch

     a dragonskin

     a bag

     recall scroll

Note the blank line at the end of the inventory.

A matching trigger might be:

Match: ^You are carrying:\n(([ ]{5}.*\n)*)[^ ]\z

This matches "You are carrying" followed by a newline, followed by any number of lines starting with 5 spaces. It then matches a line which does NOT start with a space. Finally it is anchored to the end of the text block with \z so that if there is more than one inventory recently it will find the last one.

In this case the number of lines needs to be the largest number you expect in your inventory, as the middle part of the regular expression can match more than one line. You could choose any number up to 200.

Another example matches a "who" list, which might look like this:

Connected players

  Bob

  Alice

  Nick

3 players

The regular expression could be:

Match: ^Connected players\n(?s)(.*)\n(\d*) players?\n\z

This example uses the "\n" character to indicate line breaks, and the words "Connected players" to start the list, and "X players" to end it.

Limitations on multi-line triggers

•	The higher the number of lines you specify, the slower the trigger matching will run, as it has to assemble, and then test, a larger string.

•	Multiple line triggers must be regular expressions, as the syntax for matching line breaks does not exist for normal triggers.

•	Because of the way they work some trigger processing is not available to multi-line triggers (eg. colouring lines, omit from output, omit from log).

•	They will match output from the MUD (not notes or commands that might be in the output window), even if that output was omitted from the output window by a previous trigger.

Make wildcards lower-case

If checked, any matching wildcards are forced to lower-case before being used. This lets you match on an upper-case word, but send it back to the MUD in lower case.

One-shot

If checked, once this trigger fires, it is deleted.

Convert to Regular Expression

Click to convert an ordinary trigger to a regular expression.

Change colour and style to:

If the trigger matches you can colour the matching word or line, by setting the options below.

If the trigger matches a regular expression, then only the matching portionn of the line will be changed. A non regular expression always changes the colour of the whole line.

Choose a colour from the drop-down list. The default is "no change" which means the matching text will stay in whatever colour they were to start with.

Otherwise you can choose from any of the 16 custom colours which you can set up in the custom colour configuration diaglog.

You can also choose "other" and then click on the two colours swatches which will appear to make the trigger matching text be coloured in any foreground or background colour you choose.

Both / Text / Back

If you are choosing to change the colour of the match text, you can select from the drop-down box whether the change applies to both text and background (the default), or text-only, or background only.

If you change the text only, then the underlying background colour is preserved.

If you change the background only, then the text colour is preserved, but you can highlight the word(s) with a different shade of background.

Bold

Click to make the matching text bold. This is greyed out if you do not have "show bold" enabled in the Output configuration screen.

Italic

Click to make the matching text italic. This is greyed out if you do not have "show italic" enabled in the Output configuration screen.

Underline

Click to make the matching text underlined. This is greyed out if you do not have "show underline" enabled in the Output configuration screen.

Send to:

Where to send the "send" text to. The default is to the MUD, however you can choose other places, like the output window (as a note to yourself), a notepad, or simply enter a script command in the "send" box and send to "script".

The "send-to" box lets you choose to send the "send" text to one of:

•	 world (the MUD)

•	 command (the command window)

•	 output (directly to the output window, as a note to yourself)

•	 status (to the status line)

•	 notepad - new (create a new notepad window)

•	 notepad - append (append to a notepad window)

•	 log file (directly to the log file)

•	 notepad - replace (replace an existing notepad window)

•	 world - speedwalk delay (queue for delayed send at the speedwalk rate)

•	 variable (set a variable, whose name you provide in the variable box)

•	 execute (execute through normal command parser, so aliases, speedwalks etc. will be executed)

•	 speedwalk (send to world after converting speedwalk string)

•	 script (execute as a script command in the current scripting language)

•	 world - immediate (to the MUD immediately, even if you are speedwalking)

•	 script- after omit (execute as a script command, after omitting the matching line from output, if that option was checked)

If you send to "script (after omit)", and are using Lua scripting, MUSHclient will create a global variable called "TriggerStyleRuns", into which is placed an entry for each style run in the matching trigger.

Variable:

If you have chosen "send to variable" then enter the variable to be set here.

Sound

If a sound is chosen then that will be played when the trigger matches.

Browse...

Click to browse for a sound file.

Test

Click to test the chosen sound.

No sound

Click to have no sound play.

Only if inactive

If checked, the sound is played only if the world window is not active. You can use this to play an "alert" sound if a message arrives for you (eg. Place your name in the trigger match text) but if that world window is not currently active,

Sequence:

By entering a sequence number you can make triggers evaluate in a particular order. The lower the number, the earlier the trigger is evaluated (that is, low numbers are evaluated before high numbers). If two triggers have the same sequence the evaluation order is not defined (that is, it could be anything).

Copy wildcard X to Clipboard.

You can choose to copy any of the first matching 10 wildcards to the Clipboard.

Label:

The name (label) of this trigger. Use this if you want to refer to the trigger in scripts.

Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

•	 Start with a letter (A-Z)

•	 Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Script:

Which script routine to call in your script file. The script routine must be defined with three arguments. For example, in Vbscript:

sub myTrigger (name, output, wildcards)

  world.Note "Trigger " & " name has fired!"

end sub

However in Lua all arguments are optional (as is usual with Lua function calls).

Also if you are using Lua scripting there is a fourth (optional) argument, which is a table of all the style runs in the matching trigger. Each entry has a sub table for:

•	textcolour - the RGB colour of the text in this style (number)

•	backcolour - the RGB colour of the background (number)

•	text - the actual text

•	length - the length of the style run

•	style - style bits (bold=1, underline=2, blink=4) or'ed together (eg. bold underline would be 6)

If you use "send to script (after omit)" then the style runs are also available from the global variable: TriggerStyleRuns.

Group:

You can put triggers, aliases and timers into groups, and enable or disable the entire group. If you wish to do that put a group name here.

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Dialog

 Trigger configuration list

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: dialog=IDD_EDIT_TRIGGER)


Edit variable

Name

Name of the variable.

The name must start with a letter (A-Z) and then be followed by letters, numbers, or the underscore character. (eg. MY_NAME_123)

Contents:

Contents of the variable. The variable can be of unlimited length (within reason) and may consist of multiple lines.

Edit...

Click to edit the variable contents in a larger window.

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Dialog

 Variables configuration (list)

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: dialog=IDD_EDIT_VARIABLE)


Emote to all

This sends an emote to the selected users. Your chat name is prepended, so you just need to type the emote. eg. "laughs".

Emote:

What to emote to the selected chat users.

See Also ...

Topics

 Chat system

 Getting started

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: dialog=IDD_CHAT_EMOTE_ALL)


Enter password

If you have specified a character name in the "connecting" configuration but no password, you will be prompted for it here.

Please enter password for:

Enter the character's password.

(Help topic: dialog=IDD_PASSWORD)


Find

This dialog box is a general "find things" dialog box used in various places.

Find what:

What to search for.

Match case

If checked, the "case" must match exactly (eg. "A" will not match "a").

Regular expression

If checked, the "find" text is a regular expression. See the regular expression documentation for more details.

Direction

Which direction to search ...

Up

If selected, find backwards.

Down

If selected, find forwards.

Find

Click to start the search.

Cancel

Click to cancel the find function.

Note that when finding text in the output buffer the find will find multiple occurrences of the search string, or regular expression, on the same line.

Otherwise, then only one "item" (eg. timer, trigger, alias) is returned per find or find-again operation.

See Also ...

Command

 Find (Finds data in the display area)

(Help topic: dialog=IDD_FIND)


Functions

This dialog shows a list of MUSHclient script functions, optionally filtered to a subset by the Filter edit box.

Select a function name, and click OK to see the help for that function. Alternatively, double-click the function name.

Filter

Type a word into this box to show a subset of the functions that partially match the filter word (eg. "trigger").

OK

Click to show help on the selected function.

Copy

Click to copy the name of the selected function to the Clipboard, and close the dialog box.

Lua

Click to show the help for the Lua-specific functions.

See Also ...

Topics

 Scripting

 Utilities

Command

 FunctionList (Shows a list of all scripting functions)

Dialog

 Multi-line Edit

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_FUNCTION_LIST)


General

This is a "category-separator" page - click on the preferences topic in the tree view on the left, or press Ctrl+PgUP and Ctrl+PgDn to move to each topic.

See Also ...

Command

 Preferences (Set world details (name, font, colour etc.))

(Help topic: dialog=IDD_PREFS_P0)


Generate Unique ID

This uses CreateGUID to get a unique number, and then hashes it, retaining 24 characters (96 bits) of the hash. This generates a nice, unique identifier, like this: "0a96ce42d8e0ede554d3b9ab".

You could also use it for making up words to be send by a keypad or macro which can then be caught by an alias. This lets you extend the functionality of keypads and macros to do things like expanding variables.

You could also use it as a handy "password generator", as the number sequences are hardly going to be predicable.

See Also ...

Topics

 Scripting

 Utilities

Command

 GenerateUniqueID (Generates a 24-character hashed unique string)

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_GENERATE_UNIQUE_ID)


Global change

This dialog lets you do a quick "change all" in the command window.

This is so you can replace, for instance, every linefeed with a "%R", if that is what you need.

The following special character sequences are recognised in the "find" or "replace" boxes:

\n - end of line

\t - tab character

\\- backslash character

Find:

What to search for (eg. \n )

Replace with:

What to replace it with (eg. %R)

Change All

Click to do the change.

Cancel

Click to not change.

See Also ...

Command

 InputGlobalChange (Does a "change all" in the current command)

(Help topic: dialog=IDD_GLOBAL_CHANGE)


Global preferences - activity window

Open activity window at startup

If checked, the activity window is automatically opened when MUSHclient starts up.

Update activity window

When to update the activity window ...

On New Activity

If selected, when new activity occurs.

Periodically, every:

If selected, every X seconds (where X is entered in the box).

Both

Both when new activity occurs, and every X seconds.

Activity button bar style:

Style for the activity button bar. Various colour combinations may be chosen here.

See Also ...

Dialog

 Global preferences - defaults

(Help topic: dialog=IDD_GLOBAL_PREFSP7)


Global preferences - closing options

Confirm before closing World

If checked, you are asked to confirm before each world is closed.

Offer to save world if only Variables have changed.

If checked, you are asked to confirm whether to save the world file if only the variables have changed.

Confirm before closing MUSHclient

If checked, you are asked to confirm before MUSHclient is closed.

Offer to save MXP debug windows

If checked, you are asked to confirm whether to save any MXP debug windows that might have been created.

See Also ...

Dialog

 Global preferences - printing

(Help topic: dialog=IDD_GLOBAL_PREFSP3)


Global preferences - defaults

You can define "default" (or machine-wide) settings for the following, which can override (replace) those set up in individual world files. The purpose of this is to allow you to easily set up preferred colours/triggers/aliases etc. and only have to amend them in one place to affect multiple worlds.

The settings that can be made default are:

•	Colours

•	Triggers

•	Aliases

•	Macros

•	Timers

•	Command window font

•	Output window font

To set up defaults to be shared across multiple worlds:

a) Open your favourite world, and then save as individual files your:

•	Colours

•	Triggers

•	Aliases

•	Macros

•	Timers

(there is a "save" button on each configuration screen to do this)

You do not need to do them all. For instance, if you only want to share colours, then only save the colours.

b) Use File -> Preferences -> Defaults (this dialog box) to select the files you saved in the above step

c) Also select your preferred input and output font.

d) For all worlds that are to share these saved files, open that world, and then using the appropriate configuration screen (eg. colours, triggers) check the box "override with default".

From then on, the *next* time you open that world, it will load the world, and then load (and thus overwrite) the settings you have checked as "override with default".

Also, any new worlds will use the default settings, thus new worlds will quickly take on your default characteristics.

Note that the defaults, when loaded, *overwrite* your existing settings, so that the existing triggers, colours etc. are *lost*. If you really want to keep the existing settings, then you should save the world file under a different name (thus preserving the original).

Colours:

Default colours file. Click "Browse" to browse for it.

Triggers:

Default triggers file. Click "Browse" to browse for it.

Aliases:

Default aliases file. Click "Browse" to browse for it.

Macros:

Default macros file. Click "Browse" to browse for it.

Timers:

Default timers file. Click "Browse" to browse for it.

Output Font...

Click to select default output window font.

Input Font...

Click to select default input (command window) font.

See Also ...

Dialog

 Global preferences - notepad

(Help topic: dialog=IDD_GLOBAL_PREFSP9)


Global preferences - general options

Auto connect to world on open

If checked, automatically connect to worlds when their world file is opened.

Reconnect on disconnect

If checked, automatically reconnect to a world if its connection is lost.

Open worlds Maximized

If checked, open worlds maximized.

Notify me when connection broken

If checked, display a dialog box, or message, if the connection to the world is lost. Note this may not be noticed for a while if there is not activity for that world. This dialog box may interfere with scripts that automatically try to reconnect.

Notify me if unable to connect

If checked, display a dialog box, or message, if unable to connect to a world. Note that this dialog box may interfere with scripts that automatically try to reconnect.

Notify to output window

If checked, the above two notifications are written as a line or two to the output window, rather than opening a dialog box.

All typing goes to command window

If checked, even if the "focus" is in the output window (the upper one) as soon as you type something, the focus moves to the command window.

ALT key does not activate menu bar

If checked, Alt+X combinations (eg. Alt+F) do notactivate the appropriate menus, and pressing and releasing the Alt key does not move the focus to the menu bar.

Use fixed space font when editing triggers/aliases etc.

If checked, a fixed-space font (FixedSys) is used in the trigger/alias/timer match and send boxes. This makes it easier to see what you are matching on.

Regular expressions can match on an empty string

If checked, regular expressions can match an empty string. (eg. ^$ would match a blank line). If not checked, you cannot make a trigger to match a completely empty line.

Auto-expand config screens

If checked, the configuration windows "tree view" on the left is always fully expanded when opening the configuration screen.

Use colour gradient in config

If checked, the configuration screen has a colour gradient in it, otherwise it is a solid colour.

Bleed background colour to edge

If checked, the background colour currently in force at the start and end of each line is "bled" to the very edge of the output window. This makes MUDs which use a solid background colour look better.

Smoother scrolling

If checked, scrolling is refreshed more frequently, making it look smoother.

Very smooth scrolling

If checked, scrolling is refreshed every pixel, making it look extremely smooth, however this is somewhat slower.

Show grid lines in list views

If checked, various list views (eg. lists of triggers/aliases/timers/variables) have grid lines drawn in them.

Word delimiters

These entries define what MUSHclient considers to be a "word" for the purposes of tab-completion and double-clicking. Items in these lists are considered to be *not* words. Thus, if you put a hyphen in the list, tab-completion will stop at a hyphen. Note that a space is always considered to terminate a word, it is not necessary to put a space in the list.

Tab completion:

List of delimiters to tab-completion.

Double-click:

List of delimiters for double-click to select a word.

Flat toolbars

If checked this makes the toolbar buttons have a "flat" look, if unchecked they will have a 3D look. Changes to this option take place next time you invoke MUSHclient.

Window tabs

This lets you select where the "tabbed window" interface will appear, if at all. The tabs appear at the top or bottom of the main MUSHclient window frame - one tab per open window.

You can choose between None (no tabs), Top or Bottom.

The tabs will have the world name in the case of world windows, with the number of unseen lines after the name in brackets. The lines are considered unseen if they have arrived, and the world window is not the currently-active one.

In the case of notepad windows there will be an asterisk after the window name if the window contents have been changed, but not saved.

Changes to this option take place next time you invoke MUSHclient.

Spell checker

Options for the spell checker.

Enable

If checked, the spell checker is enabled. This affects all worlds. Note that you also need to enable "Spell check on send" in the command configuration window for each world if you want automatic spell checking as you send.

Locale code

This should be the 2-character code indicating the language you wish messages to be displayed in (eg. EN for English, FR for French).

When MUSHclient starts up, it loads the resources (eg. menus, dialog boxes, etc.) from a file named xx.dll in the "locale" subdirectory - where 'xx' is the locale code - under where the MUSHclient.exe program resides. For example, for English menus, it would look for en.dll.

It also attempts to load a file named xx.lua in the same directory. This is a file which contains mappings of internal messages into their translation in other languages.

For more details see the forum posting:

http://mushclient.com/forum/?id=7953

If you are using the English language, this entry should be left at "EN".

For other languages, do not change it until you have installed the appropriate files. For example, fr.dll and fr.lua, if you are using French.

The file 'en.dll' ships with MUSHclient, and it is not necessary to have the 'en.lua' file, as the default behaviour of MUSHclient is to use internally-coded strings for its various messages.

See Also ...

Dialog

 Global preferences - closing options

(Help topic: dialog=IDD_GLOBAL_PREFSP2)


Global preferences - logging

Default log files directory...

Default directory for log files.

Auto Log when opening world

If checked, automatically turns on logging when opening worlds.

Append to log files

If checked, automatically appends to existing log files.

Confirm when closing log file

If checked, asks you to confirm before closing a log file.

See Also ...

Dialog

 Global preferences - timers

(Help topic: dialog=IDD_GLOBAL_PREFSP5)


Global preferences - Lua

Preliminary code

You can enter some initial scripting that is executed every time that the Lua script engine is created. This can be used to set up a "sandbox", that is a safe environment for your scripts.

The default behaviour is to disable the "os" library (operating system calls), which could be used to execute arbitrary commands, and rename or delete files.

Also the "io" library is disabled, which could be used to read or overwrite existing files.

To revert to the default settings, delete everything from this window, and then close and re-execute MUSHclient.

Edit...

Click to edit the code in a larger window.

Allow DLLs to be loaded

Check this to allow DLLs to be loaded by Lua code.

Only check this if you are sure that you are not going to run untrusted scripts.

We suggest that before checking "Allow DLLs to be loaded" you edit the "sandbox" code and disallow use of the package library except for trusted worlds or plugins. For example, enter these lines in the sandbox:

package.loadlib = nil      --> disable loadlib function

package.loaders [3] = nil  --> disable DLL loader

package.loaders [4] = nil  --> disable all-in-one loader

The reason for the last two lines is that doing a "require" can trigger the DLL and all-in-one loaders, which are designed to load DLLs.

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Global preferences - world lists and directories

(Help topic: dialog=IDD_GLOBAL_PREFSP13)


Global preferences - notepad

Word Wrap

If checked, notepad windows wrap at the window edge.

Window colour

Default colour for notepad windows. If both swatches are black, will default to black on white.

Parenthesis matching preferences

Below are the preferences for the "parenthesis matching" code ...

Braces nest

When checked braces can be nested (like in MUSH) so that the "current delimiter" for the end of the scan changes.

For example:

[  ( ] )  ]

In this case, with nested braces on, and starting at the left-hand side, the cursor will move to the far right-hand side.

With nested braces off, the cursor will move to the left of the middle square bracket, as the nested bracket "(" will not have any special significance.

\ escapes next character

When checked, you can "escape" the significance of the next character (including another "\") by preceding it with "\".

For example:

[  \]   ]

With "\ escapes next character" checked, the middle bracket is ignored.

% escapes next character

When checked, you can "escape" the significance of the next character (including another "%") by preceding it with "%". The behaviour in this case is identical to the " escapes next character" above. Check this for a MUSH which uses "%" as an escape character.

' quotes a string

When checked, code can include strings.

For example:

[  ']'   ]

With "  ' quotes a string" checked, the middle bracket is ignored.

... with escape inside quotes

When checked, quotes can have escaped quotes inside them.

For example:

'Press 'Enter' now'

In this example the word 'Enter' is considered part of the quoted string.

" quotes a string

When checked, code can include strings.

For example:

[  "]"   ]

With  ' " quotes a string' checked, the middle bracket is ignored.

... with escape inside quotes

When checked, quotes can have escaped quotes inside them.

For example:

"Press "Enter" now"

In this example the word "Enter" is considered part of the quoted string.

Quote string:

String to use when quoting text.

See Also ...

Dialog

 Global preferences - world lists and directories

(Help topic: dialog=IDD_GLOBAL_PREFSP10)


Global preferences - plugins

Global plugins

Plugins listed here are automatically loaded when a world is opened, or a new world is created. This lets you have a list of "global" plugins (eg. the Chat plugin) that you always want to have available.

Add...

Click to add another plugin to the plugin list.

Remove

Click to remove the selected world from the plugin list.

Move Up

Click to move the selected plugin up the list (open it sooner).

Move Down

Click to move the selected plugin down the list (open it later).

Plugins Directory...

Click to select the default directory for loading/saving plugins.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Global preferences - general options

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_GLOBAL_PREFSP12)


Global preferences - printing

Font...

Font to use when printing.

Top margin:

Top margin for the page, in millimetres.

Left margin:

Left margin for the page, in millimetres.

Lines per page:

Lines to print per page.

See Also ...

Dialog

 Global preferences - logging

(Help topic: dialog=IDD_GLOBAL_PREFSP4)


Global preferences - timers

Timer interval (seconds):

Interval in seconds for the MUSHclient timer.

What this means is that the interval set here (eg. 5 seconds) is the rate at which timers are tested to see if they have fired. If you want timers to be accurate to the nearest second, then the timer granularity must be set at 1 second. If having a timer fire to the nearest 5 seconds is satisfactory for you, then set the granularity to 5 seconds. Setting a smaller granularity improves the accuracy of timers, but may slow the program down slightly, particularly on slower PCs.

Recommended value for modern PCs: 1 (or see below).

Sub-second timers

From version 3.61 onwards you can now set timers that fire in fractional seconds (eg. in 2.5 seconds).

To enable this, the 'interval' field on this dialog must be set to zero, which means 'the finest resolution currently supported'.

In the current version this is 1/10th of a second. Thus, timers will be checked every 10th of a second, if you put zero in the timer interval here.

See Also ...

Dialog

 Global preferences - activity window

(Help topic: dialog=IDD_GLOBAL_PREFSP6)


Global preferences - tray

Show MUSHclient in

You can specify to show MUSHclient in either the normal Windows Taskbar, the "Tray" or both.

Choose icon

You can choose the icon that will be shown in the Tray from this list, or browse for you own custom icon file.

Browse...

Click to browse for your own custom icon file.

See Also ...

Dialog

 Global preferences - world lists and directories

(Help topic: dialog=IDD_GLOBAL_PREFSP11)


Global preferences - world lists and directories

Worlds to open at startup ...

World files listed here are automatically opened when MUSHclient commences execution, unless the /noauto command-line switch is used.

Add...

Click to add another world to the world list.

Remove

Click to remove the selected world from the world list.

Add Current World

Click to add the current world (the frontmost window) to the list of worlds to be opened at startup.

Move Up

Click to move the selected world up the list (open it sooner).

Move Down

Click to move the selected world down the list (open it later).

Default world files directory...

Click to select a directory to open/save world files.

See Also ...

Command

 GlobalPreferences (Global program preferences)

Dialog

 Global preferences - general options

(Help topic: dialog=IDD_GLOBAL_PREFSP1)


Global Replace

This is for doing a powerful "global replace" using Lua's string.gsub function.

The selected text (or all text in the window if none is selected) will be sent to the string.gsub function, with the specified "find" and "replacement" text being used for the function, like this:

new_selection = string.gsub (old_selection, find_text, replacement_text)

If there is an error raised by string.gsub (eg. bad regular expression) then no text is replaced.

See the documentation for string.gsub in Lua for the exact workings of this function. Also see the forum postings:

http://www.gammon.com.au/forum/?id=6034

http://www.gammon.com.au/forum/?id=6138

The first one describes string.gsub in detail. The second one amplifies on the uses you can put this dialog box to.

Find Pattern

What to search for. This is a Lua-style regular expression.

The standard patterns you can search for are:

 . --- (a dot) represents all characters.

%a --- all letters.

%c --- all control characters.

%d --- all digits.

%l --- all lowercase letters.

%p --- all punctuation characters.

%s --- all space characters.

%u --- all uppercase letters.

%w --- all alphanumeric characters.

%x --- all hexadecimal digits.

%% --- a single '%' character.

%1 --- captured pattern 1.

%2 --- captured pattern 2 (and so on).

%f[s]  transition from not in set 's' to in set 's'.

%b()   balanced pair ( ... )

Important - the uppercase versions of the above represent the complement of the class. eg. %U represents everything except uppercase letters, %D represents everything except digits.

There are some "magic characters" (such as %) that have special meanings. These are:

^ $ ( ) % . [ ] * + - ?

If you want to use those in a pattern (as themselves) you must precede them by a % symbol.

eg. %% would match a single %

As with normal MUSHclient regular expressions you can build your own pattern classes by using square brackets, eg.

[abc] ---> matches a, b or c

[a-z] ---> matches lowercase letters (same as %l)

[^abc] ---> matches anything except a, b or c

[%a%d] ---> matches all letters and digits

[%a%d_] ---> matches all letters, digits and underscore

[%[%]] ---> matches square brackets (had to escape them with %)

The repetition characters are:

+  ---> 1 or more repetitions (greedy)

*  ---> 0 or more repetitions (greedy)

-  ---> 0 or more repetitions (non greedy)

?  ---> 0 or 1 repetition only

The standard "anchor" characters apply:

^  ---> anchor to start of subject string

$  ---> anchor to end of subject string

You can also use round brackets to specify "captures", similar to normal MUSHclient regular expressions:

You see (.*) here

Here, whatever matches (.*) becomes the first pattern. This can be referred to in the replacement box as %1.

You can also refer to patterns in the regular expression. For example:

You see (.*) and %1 here

This would match "You see fish and fish here", but not "You see fish and chips here".

Note that carriage-return characters (\r) are removed from the text before being submitted for find-and-replace, so they will never appear in the selected text. They are replaced before the text is redisplayed in the notepad window.

(...)  (edit find text)

Click on the button marked "..." to open a larger dialog box for inputting the "find" regular expression more easily.

Replacement

This is the replacement text for each match, or in the case of "Call Function" (described below), the function name to be called.

For every match of the regular expression in the Find Pattern box, the replacement text will be substituted. If you use %1, %2, etc. they will be replaced by the contents of the first/second capture pattern etc.

To replace with % literally, enter %%.

(...)  (edit replacement text)

Click on the button marked "..." to open a larger dialog box for inputting the "replacement" text more easily.

Line By Line

If checked, each individual line of the selection is sent to string.gsub as an individual item. If unchecked, the entire selection is processed as a batch.

The main difference will be the processing of line breaks.

If you check "Line By Line":

•	There will never be a newline character in the text to be matched (as that is the linebreak character)

•	The symbol ^ represents the start of each line

•	The symbol $ represents the end of each line

•	You cannot write a find/replace that will join lines together

•	It will be slower to execute (particularly on large blocks of text) because the string.gsub function has to be called for each line

If you uncheck "Line By Line":

•	There may be newline characters in the text to be matched (as that is the linebreak character). You can test for these with \n, if you check "Escape Sequences"

•	The symbol ^ represents the start of the entire selection

•	The symbol $ represents the end of the entire selection

•	You join lines together by searching for \n and replacing it with something else

•	It will be faster to execute

Escape Sequences

You can enter non-printable characters in the Find and Replace boxes using the special codes documented for script function FixupEscapeSequences, eg. \n for newline, \t for tab.

Call Function

If checked, the function (which you can edit by clicking on the "Script" button), is applied to each match, rather then a simple text replacement. In this case the "Replacement" box should be the name of the required function. This is the alternative behaviour which is documented for string.gsub - supplying a function as the replacement rather than a string.

Supplying a function lets you make more powerful replacements, such as looking up a replacement word in a table, or doing things like replacing lower-case with upper-case, and so on.

The following libraries are available to your function: table, io, string, math, debug, rex, bits, compress, and utils.

You can also enter into the replacement box directly the name of a function that already exists in the installed libraries, if this will do what you need without any extra work. For example: string.upper, string.lower, utils.hash, utils.base64encode.

Script

Click this button to enter your replacement function. This is a function written in the Lua language. If you click this, and enter some text, the "Call Function" checkbox is automatically checked.

An example of doing this would be:

Find:  [<>&]

Replace: f

Line by Line: no

Call Function: yes

Script:

replacements = {

   ["<"] = "&lt;",

   [">"] = "&gt;",

   ["&"] = "&amp;",

   }

function f (str)

  return replacements [str] or str

  end

This would make an "HTML fixup" replacement, that replaces special HTML codes by the replacements shown in the table above.

Another example of using a function:

Find: %f[%a]%u+%f[%A]

Replace: string.lower

Line by Line: no

Call Function: yes

This searches for words that are in all upper-case (by searching for %u which is upper case letters), surrounded by something that is not a letter). When found the (inbuilt) function "string.lower" is called that converts it to lower-case.

To explain this a bit further, if we had simply searched for %u+ then we would also have matched on upper-case letters inside words which also had lower-case in them. I initially had the Find pattern as: "%A%u+%A". This matches one non-letter followed by all uppercase letters, followed by one non-letter. Whilst this successfully found all upper-case words, it failed on the text boundary (that is, it would not convert an all upper-case word at the start or end of the selection). However, using the little-known Lua "frontier" pattern, we detect the transition from not letters to letters %f[%a], which is also the start of the pattern, and finish off with %f[%A] which is the transition between letters to non-letters.

OK

Click OK to perform the find-and-replace on the selected text. If no text is selected the operation is performed on the entire notepad window.

If you are not happy with the results, immediately perform an Undo (Edit Menu > Undo) or press Ctrl+Z.

When you click OK the contents of the dialog box are remembered for this session of MUSHclient, over all instances of Notepad windows. Thus, if the results are not quite right, you can Undo them, re-open the dialog box, make amendments, and try again.

X characters selected. (N line breaks)

This field, next to the OK button, shows how much text is selected. If there is no selection, or all text is selected, it will read "All text selected.". The count of line breaks shows how many newline characters have been found in the selection. Thus, a selection of one line, and part of the next line, will show "1 line break" even though 2 lines may be visibly selected.

See Also ...

Topic

 Notepad

Command

 GlobalReplace (Does a global find-and-replace on the selected text using string.gsub)

Dialog

 Multi-line Edit

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: dialog=IDD_LUA_GSUB)


Go to line

Use this to go directly to any line in the output window by line number.

The line is scrolled into view, if necessary, and selected to highlight it.

Enter line number:

The line number to go to.

If you want to remember this line for later use you can use the "bookmark" function.

See Also ...

Command

 GoToLine (Go to a line number)

(Help topic: dialog=IDD_GOTO)


Highlight word

Allows you to quickly generate a trigger that highlights a word or phrase.

Highlight

Enter the word or phrase to be highlighted. If you have selected text in the output window before opening this dialog, this text will be automatically entered here.

Colour

Choose a custom colour from the combo box, or choose "Other ...".

Colour swatches

If a custom colour is selected, these will show what the custom foreground and background colours are.

If you have selected "Other ..." then you can click on the left-hand swatch to set the text colour, and the right-hand swatch to set the background colour.

Whole Word Only

If checked, this makes the trigger match only a whole word boundary. The difference is that if you highlight (say) "cat" then with "whole word only" checked it will only match "cat" on its own, however with it unchecked it would also match the first part of the word "catch".

Match Case

If checked, the trigger will only match the exact case shown, otherwise it will match upper or lower-case versions of the text.

OK

When you click OK, a trigger will be added to the world's trigger list. This trigger will be:

•	A regular expression (to match part of the line)

•	Sequence 90 (to fire before default triggers)

•	Keep evaluating (so other triggers will also match the line)

•	Repeat on same line (so multiple words on the same line will be highlighted)

•	Have empty "send" text

•	Set to change the selected text to the colour you specify

•	Group as "Highlighted Words"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Command

 HighlightWord (Highlight a word or phrase)

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: dialog=IDD_HIGHLIGHT)


Immediate

This lets you test script commands in an "immediate" window - that is, anything you type is executed as soon as you click "Run".

This lets you test script snippets before using them in a larger script.

For example (in VBscript) just enter:

world.Note "Hello, world"

and click "run".

Run

Click this to execute the script.

Close

Closes the window. Any script in it is remembered for next time you open this window (in this session of MUSHclient, for this world).

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Command

 Immediate (Allows testing of scripts)

Dialog

 Scripts

(Help topic: dialog=IDD_IMMEDIATE)


Import

Load / View Plugins ...

Click this button to view the Plugins configuration dialog. This is used to install or remove plugins. You can also access this dialog directly from the File menu -> Plugins.

Import other XML data for:

You can import MUSHclient XML configuration into the current world using this. For instance, you might import some triggers, aliases and timers, which you had saved from another world, or which you obtained in an email or from the MUSHclient Forum.

Import from:

Select where to import the XML from ...

File ...

Click to choose a file on disk.

Clipboard

Click to import directly from the Clipboard. This option will be dimmed if MUSHclient does not detect valid XML commands on the Clipboard.

Import the following:

Check the checkboxes to indicate what you want imported. What this does is narrow down the importing to the selected items. For example, you might only want to import triggers, even though the file or clipboard contains aliases as well.

General world configuration

If checked, general world configuration (like character name, IP address etc.) will be imported.

Triggers

If checked, triggers will be imported.

Aliases

If checked, aliases will be imported.

Timers

If checked, timers will be imported.

Macros

If checked, macros will be imported.

Variables

If checked, variables will be imported.

Colours

If checked, colours will be imported.

Numeric keypad

If checked, numeric keypad assignments will be imported.

Printing configuration

If checked, printing configuration will be imported.

Close

Close this dialog box once you are finished importing things or installing plugins.

See Also ...

Command

 Import (Import items from XML file)

Dialog

 Plugins

(Help topic: dialog=IDD_IMPORT_XML)


Info

Shows various pieces of information about the current world - most of it calculated at run-time.

TCP/IP address of this world:

The actual address of the world (after DNS lookup).

Lines in output buffer:

How many lines in the output buffer, and count of style runs.

Memory used by output buffer:

Amount of memory currently used in the output buffer. If the number of lines exceeds 1000, you need to click the "Calculate" button to have the usage calculated, as the calculation can be lengthy for very large output buffer sizes.

Calculate

When clicked, calculates the memory used by the output buffer. Once done, this button is grayed out, as it does not need to be done twice.

Time connection established:

When the current connection started.

Connection duration:

How long we have been connected.

Triggers:

Count of triggers in the main world, and the execution time they have taken so far.

Aliases:

Count of aliases in the main world.

Timers:

Count of timers in the main world.

Compression ratio:

Compression ratio if using MCCP (Mud Client Compression Protocol).

Received:

How many bytes (and Kb) have been received from the MUD.

Sent:

How many bytes (and Kb) have been sent to the MUD.

MXP statistics

Statistics for the MXP (Mud eXtension Protocol) parser.

See Also ...

Command

 Info (Shows information about this world)

Dialog

 Notes

(Help topic: dialog=IDD_PREFS_P15)


Info bar

This is the "info bar" which can be changed through scripting.

See Also ...

Topic

 Info bar - programmable information bar

Command

 InfoBar (Show or hide the info bar)

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: dialog=IDD_INFO)


Input Box

General input box for use by scripting.

This appears when a script calls: utils.inputbox

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_LUA_INPUTBOX)


Input Edit Box

General input box for use by scripting.

This appears when a script calls: utils.editbox

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_LUA_INPUTEDIT)


Insert Unicode Character

Use this for inserting a single Unicode character as the appropriately converted UTF-8 sequences into the Debug Simulated World Input dialog.

Character Code

This is the code number of the Unicode character. It can be entered as decimal (0 to 2147483647) or hex (0 to 7FFFFFFF). You can look up the codes on an appropriate web site (or the Unicode 5 Standard book). For example, "Greek Small Letter MU" is 03BC.

Hex

Check to have the code entered interpreted as a hex number (this is the default, as this seems to be how Unicode codes are given). Otherwise it is interpreted as a decimal number.

See Also ...

Dialog

 Debug simulated world input

(Help topic: dialog=IDD_INSERT_UNICODE)


Key name

This dialog converts a keypress into its "display" name for use with the Accelerator function.

See Also ...

Topics

 Scripting

 Utilities

Command

 KeyName (Converts a keypress into its name)

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: dialog=IDD_KEY_NAME)


Keyboard preferences

This lets you set various other options related to entering commands.

Double-click Pastes Word

If checked, if you double-click a word in the output window, it is immediately copied into the command window (however not using the Windows clipboard).

Double-click Sends Word

If checked, if you double-click a word in the output window, it is immediately sent to the the world. This would be handy for sending a command you see on the screen (eg. in help text).

Escape Deletes Typing

If checked, pressing the Esc key deletes what you have entered in the command window.

Save Deleted Command

If checked, if you delete something by pressing Esc it is saved in the Command History - this is in case you accidentally delete a long command.

Confirm Before Replacing Typing

If checked, before you replace something you have typed (eg. by using the arrow keys), you are asked to confirm you want to get rid of the current contents of the command window.

Arrow Keys Wrap History

If checked, if you are using the arrow keys to traverse the history buffer, and you reach the end of it, then you "wrap around" and go back to the other end.

Arrow Keys Traverse History

If checked, pressing an arrow key (up or down arrow) moves you up or down through the command history. If unchecked, the arrow keys merely move you around inside the current command in the command window.

Arrow Key Recalls Partial Command

If checked, and if "Arrow Keys Traverse History" is checked, and you type a partial command (eg. "eat") and then press up-arrow, then any command matching that partial command (eg. "eat meat") will be presented to you, skipping any commands that do not match.

Alt+Arrow Key Recalls Partial Command

If checked, and if "Arrow Keys Traverse History" is checked, and you type a partial command (eg. "eat") and then press Alt+up-arrow, then any command matching that partial command (eg. "eat meat") will be presented to you, skipping any commands that do not match.

Compatibility

The next options are for compatibility with other clients.

Ctrl+Z Goes To End Of Output Window

If checked, pressig Ctrl+Z takes you to the bottom of the output window.

Ctrl+P Recalls Previous Command

If checked, pressing Ctrl+P recalls the previous command.

Ctrl+N Recalls Next Command

If checked, pressing Ctrl+N recalls the next command.

See Also ...

Dialog

 Commands

(Help topic: dialog=IDD_COMMAND_OPTIONS)


Log game session

This dialog is shown when you start logging your session.

Include X lines from screen buffer in log file.

You can log retrospectively. What this means is that you can decide to log *after* seeing some interesting messages. By entering a number in this box you can specify how many previously-received lines to log.

When you first start up logging, you will be prompted as to whether you want the last "n" lines included (where "n" is the number of lines already received from the MUD, with a maximum of 500,000). If you want only recent lines, you can replace the number with a smaller one (say, 20). Or if you only want to log future output, type a "0" to replace the number displayed.

The exact number of lines that can be recalled is set in the "Output" tab of the world configuration screen. The maximum it can be set to is 500,000 lines.

What if more lines appear while I am reading this message?

The line count is automatically adjusted to allow for more lines that appear while you are reading the dialog box (or this help message!). Say you wanted 20 lines to be retained from the display buffer, but another 15 appear while you are entering the number "20". The program will actually retain 35 lines so that the ones you originally wanted appear in the log file.

The exception is that if you enter zero ("0") for the line count, then zero lines from the output buffer are retained, no matter how many appear while you are looking at the dialog box.

Comment to put in log file:

This allows you to add a free-format comment to the start of the log file (eg. describing why you are logging this particular session).

Log Output

If checked, output from the MUD is logged.

Log Commands

If checked, commands you type are logged.

Log Notes

If checked, script "notes" are logged.

Append to existing log file

If checked, any existing log file of this name is appended to, rather than overwritten.

Write world name to log file

If checked, the world name, and the date and time, are written to the log file, as a record of what world you are logging, and when.

See Also ...

Topic

 Logging

Command

 LogSession (Writes the game session out to a text file)

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: dialog=IDD_LINE_COUNT)


Logging

Standard HTML preamble/postamble

This button is active if HTML logging is select. Click it to insert a reasonable HTML preamble/postamble into the "file preamble" and "file postamble" boxes. With those commands there you could save the log to disk and open in your web browser, and it would look reasonable.

File Preamble:

Text to put at the start of the log file (or session, if you are appending to earlier sessions in the same file).

(...)

Click to edit the file preamble in a larger window.

File Postamble:

Text to put at the end of the log file.

(...)

Click to edit the file postamble in a larger window.

(?)

Click to display a help window reminding you of the special characters that can be placed in the various preamble/postamble boxes, as well as the log file name itself. This currently says ...

Special characters for date/time etc.

-------------------------------------

General

%E - MUSHclient startup (initial) directory

%F - world files directory

%L - log files directory

%n - new line (in some cases only)

%N - world name

%P - player name

Date/time

%a - Abbreviated weekday name

%A - Full weekday name

%b - Abbreviated month name

%B - Full month name

%c - Date and time representation appropriate for locale

%d - Day of month as decimal number (01 - 31)

%H - Hour in 24-hour format (00 - 23)

%I - Hour in 12-hour format (01 - 12)

%j - Day of year as decimal number (001 - 366)

%m - Month as decimal number (01 - 12)

%M - Minute as decimal number (00 - 59)

%p - Current locale's A.M./P.M. indicator for 12-hour clock

%S - Second as decimal number (00 - 59)

%U - Week of year as decimal number, with Sunday as first day of week (00 - 53)

%w - Weekday as decimal number (0 - 6; Sunday is 0)

%W - Week of year as decimal number, with Monday as first day of week (00 - 53)

%x - Date representation for current locale

%X - Time representation for current locale

%y - Year without century, as decimal number (00 - 99)

%Y - Year with century, as decimal number

%z, %Z  - Time-zone name or abbreviation; no characters if time zone is unknown

%% - Percent sign

Modification

The # flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows.

%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#% - # flag is ignored.

%#c - Long date and time representation, appropriate for current locale. For example: "Tuesday, March 14, 1995, 12:41:29".

%#x - Long date representation, appropriate to current locale. For example: "Tuesday, March 4, 1995".

%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y - Remove leading zeros (if any).

Log Output

If checked, output from the MUD is logged.

Log Commands

If checked, commands you type are logged.

Log Notes

If checked, script notes are logged.

HTML

If checked, logging is in HTML, which will attempt to preserve the colours and spacing in the world window. (Colours only if "colour" is checked).

Colour

If checked, and HTML is checked, colours are written to the log file.

Write world name to log file

If checked, the name of the current world is written to the log file.

Automatically log to this file:

This makes MUSHclient automatically log to the named log file every time that it connects to a world. If the file already exists, it is appended to.

The name of the file to automatically log to. If blank, logging will not commence automatically. You can use special strings (described above) to make the file name contain things like the date, time and world name.

Browse...

Click to browse for a file name to log to.

Preamble / Postamble

Enter some text in these boxes if you want each line in the log file to have a prefix/suffix. The preamble will be placed in front of each line, and the postamble will be placed at the end of line.  You can incorporate the date and time into this field. See below for more details.

For example, to log the time each line arrived you might put:

%H:%M ...

Output lines:

Preamble/postamble for each line of output from the MUD.

Commands:

Preamble/postamble for each line of commands you type.

Script notes:

Preamble/postamble for each line of script notes.

Raw

If checked, logging is in "raw" format. This is intended to simply copy the MUD output straight to the log file exactly as it arrives (after decompression, if MCCP is in use). This lets you make an "image" of what arrived, colour codes, MXP codes and all. You could use this later to "pipe" back into the client to test it, for example, for speed. Normally you wouldn't use this.

Omitting some lines from the log file

You can use triggers to omit lines from the log file (if they match a trigger). See "Edit trigger" for more details about doing this.

Alternatively, you can default to outputting no lines (by unchecking Log Output) and then use a trigger to send particular lines to the log.

You can also use aliases to omit outgoing messages from the log file (if they match an alias). See "Edit alias" for more details about doing this.

See Also ...

Topic

 Logging

Command

 ConfigureLogging (Sets logging options)

Dialog

 Timers

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: dialog=IDD_PREFS_P4)


Macros

Customise output from function keys and 'Game' menu.

Use this dialog to configure what is sent if you press one of the function keys (macros), for example, F2. The string you enter is sent through command processing so you can put aliases here.

Also, some items (like "quit") control what is sent if you select Quit from the Input menu.

Override with default macros

If checked, next time the world is loaded your macros are replaced with the default ones. See the help topic on "defaults" for more details.

Edit...

Click to edit a macro.

Find...

Click to find a macro based on its contents.

Find Next

Click to repeat the next find (find another one that matches).

Load...

Click to load macros from disk.

Save...

Click to save selected macros to disk.

Hint

To do more elaborate things (like expanding variables, running scripts) enter a nonsense word as what to send, and then make an alias to "catch" that word, and do the extra processing in the alias. One way of doing this is to use the Edit -> Generate Unique ID menu item to generate a unique word, like this:

381e051a828fb201b6914699

This is unlikely to be something you would normally want to type into the MUD. Then make an alias to match on "381e051a828fb201b6914699" (or whatever word you choose) and make the alias do things like expand variables, call scripts, etc.

Warning

Any accelerators which have been defined with the Accelerator function will hide a corresponding macro from being shown in the macro configuration screen, so as to avoid confusion about what the keystroke actually does.

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Commands

 AltA (Executes a user-defined macro.)

 AltB (Executes a user-defined macro.)

 AltJ (Executes a user-defined macro.)

 AltK (Executes a user-defined macro.)

 AltL (Executes a user-defined macro.)

 AltM (Executes a user-defined macro.)

 AltN (Executes a user-defined macro.)

 AltO (Executes a user-defined macro.)

 AltP (Executes a user-defined macro.)

 AltQ (Executes a user-defined macro.)

 AltR (Executes a user-defined macro.)

 AltS (Executes a user-defined macro.)

 AltT (Executes a user-defined macro.)

 AltU (Executes a user-defined macro.)

 AltV (Executes a user-defined macro.)

 AltX (Executes a user-defined macro.)

 AltY (Executes a user-defined macro.)

 AltZ (Executes a user-defined macro.)

 ConfigureMacros (Sets macro options)

 East (Executes a user-defined macro.)

 Look (Executes a user-defined macro.)

 MacroCtrlF10 (Executes a user-defined macro.)

 MacroCtrlF11 (Executes a user-defined macro.)

 MacroCtrlF12 (Executes a user-defined macro.)

 MacroCtrlF2 (Executes a user-defined macro.)

 MacroCtrlF3 (Executes a user-defined macro.)

 MacroCtrlF5 (Executes a user-defined macro.)

 MacroCtrlF7 (Executes a user-defined macro.)

 MacroCtrlF8 (Executes a user-defined macro.)

 MacroCtrlF9 (Executes a user-defined macro.)

 MacroF10 (Executes a user-defined macro.)

 MacroF11 (Executes a user-defined macro.)

 MacroF12 (Executes a user-defined macro.)

 MacroF2 (Executes a user-defined macro.)

 MacroF3 (Executes a user-defined macro.)

 MacroF4 (Executes a user-defined macro.)

 MacroF5 (Executes a user-defined macro.)

 MacroF7 (Executes a user-defined macro.)

 MacroF8 (Executes a user-defined macro.)

 MacroF9 (Executes a user-defined macro.)

 MacroShiftF10 (Executes a user-defined macro.)

 MacroShiftF11 (Executes a user-defined macro.)

 MacroShiftF12 (Executes a user-defined macro.)

 MacroShiftF2 (Executes a user-defined macro.)

 MacroShiftF3 (Executes a user-defined macro.)

 MacroShiftF4 (Executes a user-defined macro.)

 MacroShiftF5 (Executes a user-defined macro.)

 MacroShiftF6 (Executes a user-defined macro.)

 MacroShiftF7 (Executes a user-defined macro.)

 MacroShiftF8 (Executes a user-defined macro.)

 MacroShiftF9 (Executes a user-defined macro.)

 North (Executes a user-defined macro.)

 South (Executes a user-defined macro.)

 Take (Executes a user-defined macro.)

 Up (Executes a user-defined macro.)

 West (Executes a user-defined macro.)

 Whisper (Executes a user-defined macro.)

Dialog

 Edit macro

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: dialog=IDD_PREFS_P6)


Main MUSHclient window

This is the MUSHclient "split" window. The MUD name will be in the title bar, the top area is used for showing MUD output, and the bottom part (below the splitter bar) is used for the command area (input to the MUD). You can resize the command area by placing the mouse over the splitter bar and moving it up or down.

Entering commands

You can only send commands to the MUD when the "focus" is in the lower (command) window. If the focus is there, you should see a flashing cursor (vertical bar), and what you type should appear in that window. If not, make sure that window is active (click on the title bar if necessary), and press the <tab> key. The <tab> key moves the focus from the upper window to the lower (command) window.  You can also use the <esc> key to move the focus in this way. However be careful that if the focus is already in the command window, then pressing <esc> can (optionally) delete everything already typed into it.

If you have enabled "command stacking" in the command preferences, you can enter the command stack character to break a single line into multiple lines (eg. "west;up"). This effect can be temporarily disabled by entering the command stack character as the very first character (eg. ";say eat;sleep")

Editing commands

Commands are not transmitted to the MUD until you press <Enter>, so until that time, you can use the mouse, arrow keys, "home", or "end" keys to move the cursor around in the command area, editing and amending your input. You can also use the normal Windows copy (Ctrl+C), cut (Ctrl+X) and paste (Ctrl+V) commands to copy and paste text from inside MUSHclient or elsewhere.

Press Alt+Home to move the cursor to the start of the command window, and Alt+End to move to the end of it.

If you are typing script commands you can press Shift+Tab to complete a partially-typed inbuilt script function name.

Global change

If you need to make a "change all" in your command (perhaps changing every linefeed into the %r characters), then use the Global change function.

Recalling previously transmitted commands

Up to the last 5000 commands you entered (per world) are saved in an internal command history buffer. You can view this buffer at any time by pressing Ctrl+H (or select "Command History" from the Game menu). You can select (highlight) any previous command with the mouse and click the "recall" button to recall it to the command input area.

The exact number of commands that is retained is user-configurable.

Alternatively, you can recall recent commands by pressing Alt+Up-arrow to move upwards through the recent commands, or Alt+Down-arrow to move back downwards.

If you have checked the "arrow keys traverse history" box in the world configuration screen, you can review recent commands by pressing Up-arrow and Down-arrow without having to press the Alt key.

The history buffer does not record empty (blank) commands, or commands which are identical to the previous one.

You can use Ctrl+R to repeat the previous command.

Match on partial command

If you have the "Alt+Arrow Keys Recalls Partial Command" option set, then you can type a partial command (eg. "cast") and then press Alt+Up-arrow. The last command matching the partial command (in this case, "cast") will be displayed. Keep pressing Alt+Up-arrow to see earlier commands which also started with the same string.

Tab completion

This very useful feature lets you type a partial word, and then press TAB. The first word matching the partial word, searching backwards through the output window, will be used to complete the partial word. You can also specify your own list of words to be taken in advance of searching the output window.

For example, if you see:

A Dragonsnake sits here hissing!

You can type:

kill dra<tab>

You would then see the command window change to read:

kill Dragonsnake

If this is what you want, press ENTER. If not,  press CTRL+Z (undo), then right-arrow once (to move past the selected word), and add a couple more letters. For example, if there was a "drain" and a "dragonsnake" nearby, then "dra" might match on "drain".

Reviewing output from the MUD

You can easily scroll backwards through recent output by pressing "Page-Up" or "Page-Down" to scroll the display buffer forwards and backwards. You can also use:

  •	CTRL+HOME	Go to start of display buffer

  •	CTRL+END	Go to end of display buffer

  •	CTRL+UP-ARROW	Go up one line

  •	CTRL+DOWN-ARROW	Go down one line

  •	CTRL+PAGE-UP	Go upwards one screenfull

  •	CTRL+PAGE-DOWN	Go downwards one screenfull

Pausing output

If you have an interesting message that you are trying to read, but can't because recent output is causing the screen to keep scrolling, you can temporarily "pause" the output by pressing:

Ctrl+Space

Although new output will be received and processed (and triggers acted upon), the display buffer will not scroll automatically, until you un-pause it by pressing Ctrl+Space again.

Resizing the window

You can resize the MUSH window in the usual way, but please note that the display area is fixed to show a certain number columns of output per line. This number is fixed in the "Output" tab of the world configuration screen.

Changing the display and command font

You can change the font (typeface) being used in the display and command area, on a per-world basis, by using the "World Configuration" menu item from the "Game" menu (or pressing Ctrl+G), and then selecting the "Screen" tab. Click on the "Font" button and choose your desired font and size. (In general, monospaced fonts (eg. Courier) will work better than proportionally spaced fonts, because many displays [eg. WHO lists] are designed to be displayed with a monospaced font).

Once you have closed the " World Configuration" dialog box, the font chosen will the used to display the output, and for command input, for the chosen world. This will only become permanent if you save the world details (File > Save).

Contents of status line

 The status line shows (for the current world):

  •	Pause status (double-click to pause/unpause)

  •	MUD name (click to select a different open world)

  •	Time connected (double-click to reset to zero)

  •	Number of lines received (double-click to go to a line by number)

If you have paused output by pressing CTRL+SPACE, then the word "PAUSE" appears to warn you that new output will not automatically appear. However if you have scrolled backwards through your output buffer the word "PAUSE" is replaced by "MORE" to warn you that you are not at the end of the output window.

Logging status

If output is being logged, then the word "LOG" will appear to confirm that logging is on.

Caps lock

If you have "caps lock" on then the words "CAP" will appear to confirm this.

Switching world windows

You can switch between multiple open worlds by simply typing Ctrl+Tab, or in the case of the first 10 opened worlds Ctrl+1 (for world 1), Ctrl+2 (for world 2), and so on.

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Getting started

 Program features

 Speed walking

 Timers

 Triggers

Dialog

 Commands

(Help topic: dialog=IDR_MUSHCLTYPE)


Make Multi-Line Trigger

Allows you to quickly generate a multi-line trigger.

Trigger on:

Enter the multi-line text to be matched. This is automatically generated from selected text in the output window, if any. The text is converted to a regular expression, so that things like .()[] will be "escaped" with a backslash in front of it.

You do not need to enter \n for a newline, these will be generated automatically at each linebreak.

Match Case

If checked, the trigger will only match the exact case shown, otherwise it will match upper or lower-case versions of the text.

OK

When you click OK, a trigger will be added to the world's trigger list. This trigger will be:

•	A regular expression (as required for multi-line triggers)

•	Multi-line, with the line count set to the number of lines in the match text

•	Keep evaluating (so other triggers will also match the line)

•	Send to output

•	Send the entire matching trigger ("%0")

•	Group as "Multi Line"

The intention is that you would then edit the multi-line trigger in the trigger configuration for the world and make it do whatever you want. You may also want to replace variable parts of the text with (.+) or similar to act as wildcards.

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Command

 MakeMultiLineTrigger (Make a multi-line trigger)

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: dialog=IDD_MULTILINE_TRIGGER)


Map Comment

This dialog lets you add a special comment to the auto-mapper sequence. You can use this for free-form notes about what the mapper is doing now (eg. "Outside city of shadows")

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Command

 DoMapperComment (Sends comment to auto-mapper)

Dialog

 Special Map Movement

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: dialog=IDD_MAP_COMMENT)


Mapper

The auto-mapper allows you to remember which directions you have walked to make it easy to retrace your steps next time, or to reverse your route and go back.

Enabled

If checked, the mapper is enabled (active).

Special Move...

Click to make a special move that the mapper will not automatically recognise (such as "teleport", "open gate", "open door").

Current route:

Shows the currently-recorded route.

Reverse route:

Shows the reverse of the current route.

Failure message:

Enter a message here that you receive from the MUD to show you could not go the way you just attempted to go.

eg.

You type "north"

MUD replies "Alas, you cannot go that way."

If you might receive multiple messages you should make a "regular expression" message, that lists alternatives. You can use the "|" symbol to do that. For example:

(You cannot go (north|south|east|west).)|(The door is locked)

Regular Expression

If checked, the failure message is a regular expression.

Remove All ...

Click to remove all directions from the current auto-map sequence.

Remove Last

Click to remove the last directions from the current auto-map sequence. You might do this if your last attempt to walk failed, but the failure was not detected by the failure message.

Take Reverse Route

Click to immediately speed-walk the directions shown in the "reverse route" box. You might do this if you had walked into a dangerous situation and quickly wished to backtrack.

Make Alias ...

Make an alias from the current auto-map route.

Make Reverse Alias ...

Make an alias from the reverse of the current auto-map route.

Remove Backtracks

If checked, backtracks are removed from mapping sequence, if unchecked they are left there. A backtrack is defined as going one direction, immediately followed by its "opposite". For example, north followed by south. The intention here is that if you are walking along a street, say, and poppping into shops, trying to find the right one, the auto-map sequence won't be filled up with a lot of "change of mind" directions. eg.

Without backtracks removed:

N E W N E W N E W N E

With backtracks removed:

4N E

Convert to Regular Expression

Converts the failure message from a standard message to a regular expression.

Edit Failure Message

Opens a dialog box to make editing the failure message easier.

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Command

 Mapper (Shows the mapping dialog)

Dialog

 Special Map Movement

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: dialog=IDD_MAPPER)


Missing script procedure names

This dialog shows which script routines were required by triggers/aliases/timers and other things (such as "world open") but were not found in your script file.

This to warn you that the named script routines will not be called.

We recommend that you either add the appropriate script routines to the script file, or remove the requirement to call them from the appropriate triggers/aliases etc.

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

(Help topic: dialog=IDD_MISSING_ENTRY_POINTS)


Multi-line Edit

General-purpose dialog for editing text (like trigger/alias match/send text).

This is used for multi-line input.

Functions ...

If the dialog is being used for editing a script a "Functions..." box will be present. Clicking this will show a help dialog box listing all MUSHclient script functions.

If a word is selected, or the cursor is on a word in the multi-line edit dialog, then that word will be used as the filter for the help dialog. For example, position the cursor inside "AddTrigger" and click the "Functions" button.

Complete ...

If the dialog is being used for editing a script a "Complete..." box will be present. Clicking this will invoke a list box with all function names that start with the selected word (or the word adjacent to the cursor). You can choose one from the list and press (Enter) to accept the function name, or (Esc) to leave the text unchanged.

Go To Line ...

If the dialog is being used for editing a script a "Go To Line ..." box will be present. This lets you jump to a line in the dialog by line number. This is handy when an error message says "error in line 42" (or similar).

See Also ...

Dialog

 Functions

(Help topic: dialog=IDD_EDIT_MULTILINE)


MUSHclient

Welcome!

Welcome to MUSHclient - the fast, easy-to-use MUD client program. We hope you enjoy using it.

Getting Started

Getting started with MUSHclient is easy. The fastest way to connect to a MUD is to use the Connection menu, and select Quick connect (SHIFT + CTRL + C).

Fill in the following fields:

World name

This is the name of the MUD. It is used to label the window for that MUD when you are connected. It can be anything you like, for example "Realms of Despair".

TCP/IP address

This is the address of the MUD. It can be expressed as a "dotted-decimal" number, or just the name of that MUD's server, for example "realmsofdespair.com", or "216.251.47.10". (Don't type the quotes).

Port number

This is the port that is used to connect to that MUD, for example, "4000".

When you click on OK you will be connected to the specified world, and you can start playing. To change various options, use the World Configuration dialogs (CTRL+G).

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Getting started

 Program features

 Speed walking

 Timers

 Triggers

Dialog

 Quick Connect

(Help topic: dialog=IDR_MAINFRAME)


MXP / Pueblo

MXP active/inactive

Shows whether MXP is active or not at present.

Use MXP/Pueblo:

Select when to switch into MXP mode. Choices are:

* When the MUD commands - the preferred choice.

* When the MUD queries if you support MXP or not.

* Always on - usually only use this for testing MXP

* Always off - used to inhibit MXP.

Detect Pueblo initiation string

If checked switch into Pueblo mode when one of the following strings arrives:

"This world is Pueblo 1.0 Enhanced"

"This world is Pueblo 1.10 enhanced."

MXP debug level:

Select level of MXP errors to display. Choices are:

* None - no errors or warnings are shown

* Errors - major errors in MXP tags are shown (in a separate text window)

* Warnings - shows doubtful MXP tags

* Information - shows some pure information messages (eg. when starting up)

* The lot - shows every tag as it arrives

Each level includes the previous level (eg. selecting warnings will also show errors).

Hyperlinks

Customise format for MXP hyperlinks.

Custom link colour:

Click on the colour swatch to choose the colour for MXP hyperlinks.

Use custom link colour

If checked, use the custom link colour.

MUD can change link colour

If checked, let the MUD override the custom link colour if it wants.

Underline hyperlinks

If checked, hyperlinks are underlined.

MUD can remove underline

If checked, the MUD can remove the underline from hyperlinks.

Save hyperlink mouse clicks in history

If checked, if you click a hyperlink, the hyperlinked text is entered into the command history (eg. if the hyperlink sends "north" then "north" is entered in the command history).

Echo hyperlink mouse clicks in output

If checked, if you click a hyperlink, the hyperlinked text is echoed in the output window.

Ignore colour changes

If checked, ignore attempts by the MUD to change the text/background colour, except through ANSI sequences.

Send AFK response

If checked, respone to the MXP "afk" tag.

MUD can change some options

If checked, the MUD can configure some of the client options itself (eg. allowing itself to change hyperlink colours).

Reset tags

CLick to reset outstanding tags. You might do this if the MUD had somehow gone into underline mode, and you had pages of underlined text. Clicking "reset" will set the text back to normal.

See Also ...

Topic

 MXP - Mud Extension Protocol

Command

 ConfigureMxpPueblo (MXP and Pueblo configuration)

(Help topic: dialog=IDD_PREFS_P22)


MXP script routines

This dialog specifies the name of the script routines that are to be called if MXP is active.

Startup:

Called when MXP starts up.

eg.

sub OnMXPStartup

  Note "MXP starting up"

end sub

Shutdown:

Called when MXP closes down.

eg.

sub OnMXPShutdown

  Note "MXP closing down"

end sub

Opening tag:

Called for an opening tag.

This should be define as a function that returns a number.

If the value (a number) is not zero, then the tag will not be acted on. This lets you customise the way MUSHclient reactions to MXP/Pueblo tags. For example, you might want to omit tags that change the font color, or tags that underline text. See below for an example.

It is called in two places:

a) For the actual tag which appears in the MUD output; and

b) If this tag is a server-defined tag (using <!ELEMENT>) then for each of the "built-in" tags that the server-defined tag calls.

For example, if you had this definition:

<!ELEMENT foo "<b><i>" >

And later on the MUD sent:

<foo>Some text</foo>

The opening "<foo>" would cause the "MXP start tag" routines to be called for the following *three* tags:

i) foo

ii) b

iii) i

In other words, once for the actual tag sent (<foo>), and once each for the tags that are called *by* <foo>.

If the routine for "foo" returned true, then "foo" is cancelled and the following text is not set to italic, nor bold.

However if "foo" returns false, but "b" returns true and "i" returns false, then the text is merely made italic.

Here is an example of how you might write such a function:

function OnMXPStartTag (name, args, mylist)

if name = "foo" then OnMXPStartTag = false ' allow <foo>

if name = "b" then OnMXPStartTag = true ' disallow <b>

if name = "i" then OnMXPStartTag = false ' allow <i>

end function

Note that if you cancel a tag sent by the server, then you will probably get a "closing tag with no opening tag" warning (warning number 5005). You might want to suppress that if it gets annoying above for how to do that.

Closing tag:

Called for a closing tag.

It is passed two arguments - the name of the tag, and the "text" which is the data that appeared between the opening and closing tags.

sub OnMXPEndTag (name, text)

  world.AppendToNotepad "MXP", _

       "Closing tag: " + name + vbCRLF

  world.AppendToNotepad "MXP", _

       "Text: " + text + vbCRLF

end sub

Set variable:

This is called when a variable is set by MXP. You are passed two arguments, the variable name, and its new contents.

sub OnMXPvariable (name, contents)

  world.note "Var " + name + " set to " + contents

end sub

Error:

A script routine to be called on an MXP error.

If the value (a number) is not zero, then the error message will not be displayed in the message window. This lets you fine-tune the messages that appear there - for example, omitting errors or warnings that you are not interested in. Here is an example:

eg.

function OnMXPError (level, number, line, message)

  If number = 20001 then OnMXPError = true

end function

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Scripts

(Help topic: dialog=IDD_MXP_SCRIPTS)


Name generator

Generated name:

The randomly-generated name. Click on "try again" if you don't like it.

Copy

Copy the generated name to the Clipboard.

Try again

Generate another random name.

Send to World

Send the generated name straight to the MUD.

Close

Close this dialog.

File name

The current names file - which has rules for generating the name.

(...)

Click on the "..." button to browse for a different names rule file.

See Also ...

Command

 GenerateCharacterName (Generates a random MUD character name)

(Help topic: dialog=IDD_GENERATED_NAME)


New Spell-Check Dictionary

File Name:

Choose a new spell check dictionary.

Browse...

Browse for a dictionary.

Language

Choose the language.

See Also ...

Topic

 Spell checker

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: dialog=NEWLEXDLG)


Notepad window

This is the window for the built-in notepad.

It is primarily intended to allow you to easily enter scripts for stand-alone script files.

If you are typing script commands you can press Shift+Tab (or Ctrl+Space) to complete a partially-typed inbuilt script function name.

Various helper functions are available from the menus.

ASCII art

Lets you insert "large" letters made up of text.

Go to brace

Lets you find or select the matching brace - useful for MUSHcode or for script languages that are dependent on brackets.

Conversions

Various conversions are available from the Convert menu, such as case conversion, line wrapping, quoting text for use in the Forum, and so on.

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: dialog=IDR_NORMALTYPE)


Notes

This screen provides you with "free format" notes, on a per-world basis.

It does not have an other special significance for the program, it is there for you to make any notes you may care to make about the current world.

Suggested uses

* Notes about interesting/friendly characters you meet

* Directions for how to get from Place A to Place B

* Work area for keying in long MUD commands, which can then be copied and pasted into the command input area when ready

* Notes about what you are planning to do next time you connect, or what equipment you need to find

* Copy interesting conversations from the MUD and paste them here for future reference

Load...

Click to load a text file into the notes area.

Save...

Click to save the notes area into a text file.

Find...

Click to find a particular word inside the notes.

Find Next

Click to repeat the last find.

See Also ...

Command

 ConfigureNotes (Set notes about this world)

(Help topic: dialog=IDD_PREFS_P11)


Output

Enable beeps:

If checked, beeps (hex 07 characters) received from the MUD will play the system beep sound.

Browse...

Click to browse for a sound file (.wav file) to play instead of the system beep.

Test

Click to test the current beep sound.

UTF-8 (Unicode)

If checked, incoming text will be treated as UTF-8 (Unicode characters encoded using the UTF-8 encoding system) and displayed as such. This will allow different character encodings (Greek, Chinese, Japanese, Russian etc.) to be displayed correctly. Due to the difficulty of testing this properly, this is somewhat of an experimental feature. Important - in order to display Unicode characters properly, you must use a Unicode font. Some fonts do not have the character encodings for Unicode characters. An example font to try would be Lucida Console, or Lucida Sans Unicode.

Text offset from edge (pixels):

Enter a number from 0 to 20 to offset the output window down, and to the right, of the edge of the window. You can use this is you find the text annoyingly close to the window edge.

Line spacing (pixels):

Enter the number of pixels that you want each line of text to be apart. You can use this to widen the gap between lines. For a 9-point font, a reasonable figure might be 15 points. Make zero to take the default font spacing.

Font...

Click to choose the font to use in the output window (the upper window).

Override with default

If checked, the default font (set in Global Preferences) is used intead of the world's font.

Show bold

If checked, bold (highlight) characters from the MUD show as bold (thicker). If unchecked they are rendered in the same font as normal characters.

Show italic

If checked, italic (and blink) characters from the MUD show in italic. If unchecked they are rendered in the same font as normal characters.

Show underline

If checked, underline characters from the MUD show underlined. If unchecked they are rendered in the same font as normal characters.

New activity sound

You can play a nominated "sound" file when new activity arrives for a MUD that is not the frontmost window.

Then, when output arrives for this MUD, and the MUD's window is not at the front, the nominated sound will be played.

Browse...

Click to select a "wave" file (ie. a file whose name ends in .WAV), a "MIDI" file (ie. a file whose name ends in .MID), or a sequencer file (ie. a file whose name ends in .RMI).

Test

Click to test the new activity sound.

No sound

Click if you do not want a new activity sound played.

Number of lines in output buffer:

Enter the number of recent MUD output lines to save (for scrolling back purposes). The higher the number, the further you can scroll back. The maximum is currently 500,000 lines. However, if you have multiple worlds open at once, all set to remember the maximum number of lines, you may find MUSHclient will eventually consume quite a bit of memory, as these lines are saved in memory.

If you find your system running low on memory, try reducing the number of lines here.

You may find a sharp degradation of performance if you choose to store so many lines in your output buffer that some have to be "paged" to disk. The degradation of performance is due to the fact that memory access speeds (usually very fast) are degraded to disk access speeds (somewhat slower). If this happens, try reducing the size of your output buffer. Smallish figures like 5,000 lines should be fine, however you may find problems storing 100,000 lines or more, depending on how much system memory you have installed. Alternatively, since memory is cheap these days, you could install more memory.

Wrap output at column number:

When this is checked, output from the MUD is wrapped at the nominated column in such a way that words are not broken into two (the line is wrapped at the previous space). You can choose to wrap at a column between 20 and 500.

If you are using a small font (or have a large screen) you may wish to wrap output at more than column 80. If you like using a large font, or have a small screen (or both) you may prefer to wrap output at a smaller column size (say, 40).

Show Line Information

When this is checked, if you move the mouse over any line in the output area for about a second, a "tooltip" window will pop up and show the line number (since the start of the session), the date/time it was received, and the word "(input)" if you typed the line yourself, or "(note)" if the line was generated by the "note" command in a script. The "tooltip" window will automatically disappear after about 5 seconds, or if you move the mouse, or if the window is scrolled.

Start Paused

If this is checked, this world will start "paused" next time you connect to it.

Auto Pause

If this is checked, the output window will pause if you scroll backwards to view previous output. It will then un-pause when you return to the bottom of the window (eg. by pressing Ctrl+End).

Un-Pause on send

If this is checked, sending a command to the MUD will un-pause the output window. The intention here is that you may have paused the window while you scroll back and look at something, but as soon as you enter a new command, want to see the effect that it has.

New activity flashes taskbar

If this is checked, if there is new activity in this world, and MUSHclient is not the foreground program, then its icon on the Windows taskbar will flash, to alert you that there is new activity for the world.

Disable compression

If this is checked, decompression of text from a server supporting MUD Client Compression Protocol (MCCP) will be disabled. You would not normally check this unless you are having problems with compressed data.

Indent paragraphs

When this is checked, when output from the MUD is wrapped at column 80, the subsequent lines of paragraphs are indented by a single space, to make it easier to recognised new paragraphs. If you do not wish this to happen, uncheck this option.

Negotiate About Window Size (NAWS)

If checked, when you resize your window, a special telnet sequence will be sent to the MUD server to let it know your screen width and height. This is helpful for some servers that automatically "page" output depending on the client window size. If you don't think you need it, leave it unchecked.

Adjust width to size

By clicking on this button the column number to wrap at will be selected as the closest that text can wrap at the edge of the current window size. Use this to adjust the output width to maximize the amount you can fit into the window size you have chosen.

Adjust size to width

By clicking on this button the window size will be adjusted to exactly fit the number of columns you have selected for wrapping purposes. Use this to have the output window the correct width for your chosen number of columns.

Auto-wrap to window size

If checked, when you resize the world window, the number of columns that MUD output wraps at is automatically recalculated to match the new size.

Alternative inverse/highlight display

This selects a different way of display inverse highlighted text.

Show connect/disconnect message

If checked, a message is entered in the output window every time you are connected and disconnected.

Copy selection to Clipboard

If checked, selecting text in the output window automatically places it on the clipboard, without needing to select the Copy command.

HTML

If checked, automatically-copied text is copied in HTML format.

Convert IAC EOR/GA to new line

If checked, incoming IAC EOR or IAC GA sequences are converted to newlines. This lets you put triggers on prompt lines and have them fire immediately, if the MUD terminates prompts with IAC EOR (0xFF 0xEF) or IAC GA (0xFF 0xF9).

Also, the sequence IAC WILL EOR will be responded to with IAC DO EOR (or IAC DO EOR) if the option is checked, and IAC DONT EOR if the option is not checked. However in this case EOR is 0x19.

Telnet Terminal Type:

Enter the type of terminal that MUSHclient reports when doing telnet negotiation.

See Also ...

Command

 ConfigureOutput (Sets output options)

(Help topic: dialog=IDD_PREFS_P14)


Paste

When sending a data to a MUD you have the option to prepend or append strings to your text (in other words, put text before and/or after each line, and the entire clipboard).

Note that there will always be a "linefeed" sent at the end of each line, you do not need to send one yourself.

Programming a MUD

If you are writing a program for an LP MUD you might want to start with:

<commands to start up the internal editor>

Then at the start of each line:

<command to insert a line>

Then at the end of the file:

<command to exit from the editor>

Echoing messages

Alternatively, you may wish to echo a message to someone that you heard elsewhere (e.g. from email). In this case you might wish to put, at the start of each line:

say

so that you "say" the contents of the clipboard.

1. Send this at the start of a "paste to world":

This string is sent once, at the start of a "paste" operation. It could be used to enter programming mode on a MUD, if necessary. This string can consist of multiple lines, with "carriage returns" between each line.

2. Send this at the start of each line:

This string is sent at the start of each line from the clipboard. It could contain any special prefix that you need at the start of each line, for example, the word "say ".

3. Send this at the end of each line:

This string is sent at the end of each line from the clipboard.

4. Send this at the end of a "paste to world":

This string is sent once, at the end of a "paste" operation. It could be used to exit from programming mode on a MUD, if necessary. This string can consist of multiple lines, with "carriage returns" between each line.

Delay between lines:

You can set a delay of up to 10 seconds between each line of text that is sent to the world. This is designed to give the server time to respond. Time is specified in milliseconds (1000 milliseconds to one second). You should keep this time as short as possible to avoid lengthy delays on doing a send. A reasonable figure might be 100 (1/10 of a second).

Every X lines

This is the number of lines that are sent before the delay (above) is invoked. Thus, you could set it up to delay 2 seconds every 100 lines.

Commented Softcode

This allows you to send commented softcode to a MUSH (MUX, or similar). See the description for "sending and pasting" for more details about that.

Echo to output window

If checked, the sent text is echoed to the output window, otherwise it is not.

Confirm on each "paste to world"

If checked, you are asked to confirm the above settings each time you paste to a MUD. If unchecked, these options are taken "as is".

See Also ...

Topics

 Commented softcode

 Sending to the world

Command

 ConfigurePasteToWorld (Sets 'paste to world' options)

Dialog

 Confirm preamble and postamble for pasting or sending file to the world

(Help topic: dialog=IDD_PREFS_P13)


Plugin wizard - Aliases

Select the aliases to be moved from this world to the plugin.

Click to select (use Ctrl+click or Shift+click to select multiple items) the aliases that are to appear in the plugin.

Select All

Click to select all in the list.

Select None

Click to select none in the list.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Timers

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE4)


Plugin wizard - Comments

Comments

The comments in the comments box will appear inside the plugin as XML comments. They are intended for notes to the plugin developer, or for people who may want to modify the plugin. They do not appear as part of the plugin "help" text.

Because of XML rules, the comments may not contain the character sequence "--" (two hyphens in a row).

If you want to use hyphens (to make a line for instance), use hyphen-space-hyphen (eg. - - - -).

Edit...

Click to edit the comments in a large window.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Name and Purpose

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE8)


Plugin wizard - Description

Description

Enter a description of what the plugin does (can be lengthy). It is stored in the plugin as "help" for the plugin user.

Edit...

Click to edit the description in a larger window.

Generate 'Help' Alias

If checked, the plugin will include a "help" alias which will show the description text.

Name:

The name for the help alias.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Triggers

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE2)


Plugin wizard - Name and Purpose

Name:

Name of this plugin - between 1 and 32 characters.

Purpose:

Short description - up to 100 characters.

Author:

Name of author - up to 32 characters.

Requires:

Which version of MUSHclient is required to run it. The earlier the better (so that people do not need to upgrade unnecessarily), however if your plugin uses script commands, or other features that only appeared in a particular version, that is the version number you should put here.

Date Written:

Date written - automatically generated.

Version:

Plugin version - defaults to 1.

ID:

Unique plugin ID - automatically generated.

Warning

Once you click the "Create" button and any triggers/aliases/timers/variables which you selected (in the other configuration screens) will be REMOVED from your world file and placed in the plugin.

The purpose of this is that the relevant triggers etc. should be moved from the "main" world file to the plugin file, otherwise you would have two lots of them when you tested the plugin, quite possibly causing a lot of confusion. However these changes will not actually occur until you save the world file.

Create ...

Click to write the plugin to disk as a separate file.

Warning - if you click "create" and then cancel the file selection dialog, you will not be returned to the plugin wizard, so any selections/entries you made will need to be redone.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Command

 PluginWizard (Invokes the plugin creation wizard)

Dialog

 Plugin wizard - Description

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE1)


Plugin wizard - Script

Language:

Language to be used in the plugin.

Include Standard Constants

If checked, an "include" line will be generated to include the appropriate "standard MUSHclient constants" for the selected language. These are files that ship with MUSHclient, that contain constant names for error messages, and flags for things like AddTrigger.

Script text

This is the script (copied from your script file) that will appear in the plugin.

If only part of the script is relevant to the plugin you should remove the unwanted parts before creating the plugin.

Edit...

Click to edit the script in a larger window.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Comments

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE7)


Plugin wizard - Timers

Select the timers to be moved from this world to the plugin.

Click to select (use Ctrl+click or Shift+click to select multiple items) the timers that are to appear in the plugin.

Select All

Click to select all in the list.

Select None

Click to select none in the list.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE5)


Plugin wizard - Triggers

Select the triggers to be moved from this world to the plugin.

Click to select (use Ctrl+click or Shift+click to select multiple items) the triggers that are to appear in the plugin.

Select All

Click to select all in the list.

Select None

Click to select none in the list.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Aliases

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE3)


Plugin wizard - Variables

Select the variables to be moved from this world to the plugin.

Click to select (use Ctrl+click or Shift+click to select multiple items) the variables that are to appear in the plugin.

Select All

Click to select all in the list.

Select None

Click to select none in the list.

Retain State (Remember Variables)

If checked, the plugin will be set to "retain state". This means that variables used in the plugin will be remembered on a per world/per plugin basis.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Script

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINWIZARDPAGE6)


Plugins

Plugins list

This list shows the active plugins for this world. You can click on one or more of them to take an action on it (such as removing it).

Add...

Click to add a new plugin.

Remove

Click to remove the selected plugin(s).

ReInstall

Click to cause the plugin to be removed and re-installed. You might do this after upgrading the plugin file.

Show Info

Click to show the plugin's purpose (description) in a separate editor window. You will need to then close this dialog box to read the description.

Enable

Click to enable all selected plugins. If the plugin was previously disabled, the script function OnPluginEnable (if it exists) in the plugin will be called.

Disable

Click to disable all selected plugins. Disabled plugins no longer react to events (like triggers firing, aliases, timers, connect/disconnect events). If the plugin was previously enabled, the script function OnPluginDisable (if it exists) in the plugin will be called.

Edit

Click to edit the plugin file. You can also double-click an item in the plugin list to edit its file.

You can also RIGHT-double-click a plugin name in the plugin list to open its "state" file, if any.

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Command

 Plugins (Shows plugins active for this world)

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: dialog=IDD_PLUGINS)


Preferences

This is the world's preference configuration screen.

Select an item from the tree-view.

Click on a "+" sign to expand a section of the preferences.

Use Ctrl+PgUp or Ctrl+PgDn to move to each preferences pane.

(Help topic: dialog=IDD_PREFERENCES)


Printing

If you print from your output screen to your printer you can configure how each colour is to appear. MUSHclient prints in black-and-white only, however you can specify that various colours can have different styles (eg. red might be shown as bold, and green as italic).

Use the checkboxes to select the printing style for each normal, and bold, colour combination.

See Also ...

Command

 ConfigurePrinting (Printing options)

(Help topic: dialog=IDD_PREFS_P20)


Problem parsing regular expression

There has been a problem parsing the regular expression.

Error

This is the error message returned from the regular expression parser.

The error occurred at column ...

This is the column the error is at.

Expression

This box contains the regular expression with a line of hyphens and a carat (^) pointing to the exact column at which the error was detected.

OK

Click OK once you have read the message, and then correct the regular expression.

See Also ...

Topics

 Aliases

 Lua LPEG library

 Lua string functions

 Regular Expressions

 Triggers

(Help topic: dialog=IDD_REGEXP_PROBLEM)


Proxy server username and password

If you connect via a proxy server you can optionally enter the logon name and password for the proxy server.

Proxy Server Logon Name:

Proxy server logon name.

Proxy Server Password:

Proxy server password.

(Help topic: dialog=IDD_PROXY_PASSWORD)


Quick Connect

This screen is for quickly connecting to a MUD. You merely need to enter:

•	A world name

•	The TCP/IP address (or name) of that world

•	The port number

This information is usually provided by MUD lists which are available from the Internet.

MUD lists can be found at:

http://www.gammon.com.au/links/muds.htm

World name:

The internal name (used to identify the MUD to you) - eg. "Realms of Despair"

TCP/IP address:

The IP address (name or dotted decimal number) of the MUD - eg. "games.org" or "66.51.106.87"

Port Number:

The port number for the MUD (you can find this from MUD lists). Often it is 4000 for Diku MUDs, or 4201 for MUSHes.

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Getting started

 Program features

 Speed walking

 Timers

 Triggers

Commands

 GettingStarted (Help on getting started with MUSHclient)

 Introduction (Getting Started)

 QuickConnect (Quickly establishes a connection to a new world)

Dialog

 World name and TCP/IP address

(Help topic: dialog=IDD_QUICK_CONNECT)


Recall

Not used  now, I think. :)

(Help topic: dialog=ID_RECALL_WINDOW)


Recall

This is sort-of like a "batch find". It lets you scan the output window and quickly retrieve matching lines into a separate window. For example, you might recall each line starting with <CHAT>.

If text is currently selected in the output window, lines matching the selected text are recalled without this dialog box being displayed.

Recall What:

If you are not using regular expressions, simply recalls every line which has the "recall what" text in it (anywhere in the line).

If you are using regular expressions, recalls lines matching that expression.

Match case

If checked, the "case" must match exacly (eg. "cave" and "Cave" would be considered different words).

Regular expression

If checked, the "Recall what" text is processed as a regular expression. See "regular expressions" for more details.

For example:

^<CHAT>

This would match lines starting with <CHAT>.

Examine X lines from end.

You can specify how many lines to go back, in case you have thousands of lines, and only want to recall over the last 200 (say).

Output

If checked, examine lines marked as "output" (which arrived from the MUD).

Commands

If checked, examine lines marked as "commands" (which you typed).

Notes

If checked, examine lines marked as "notes" (which were done by scripts).

Line Preamble:

You can put a preamble in front of every line (eg. "%H:%M>") - this example would show the time each line was created.

?

Click the "?" button to see options for entering into the line preamble box.

Find

Click to commence the recall operation.

See Also ...

Topics

 Aliases

 Lua LPEG library

 Lua string functions

 Regular Expressions

 Triggers

Command

 RecallText (Recalls all lines matching a string into a separate window)

(Help topic: dialog=IDD_RECALL)


Scripting Error

This dialog is shown if there is an error in the scripting engine.

Copy Details

Click to copy the error information to the Clipboard (so you can email it to someone or post the error on the forum).

Error number:

The decimal error number.

Event:

Where the error occurred (eg. Line and column)

Raised by:

Which world (and which plugin if applicable) caused this error message.

This field does not appear for script errors that are not related to any particular world (eg. dialog filters, spell checker, notepad find-and-replace).

Description:

A description of the error from the script engine.

Called by:

Where the script was called from (eg. Which trigger, alias etc.)

Show errors in output window next time

If you check this, future errors for this world will not be shown in this dialog box, but instead will be sent directly to the output window. To change this behaviour, see the world configuration, scripting configuration tab.

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Scripts

(Help topic: dialog=IDD_SCRIPT_ERROR)


Scripts

This screen is used to define parameters for scripting MUSHclient. Scripting allows you to create custom triggers, aliases and timers that react in ways limited only by your imagination.

Available script functions are documented under the Help menu -> Functions List.

Scripting Language:

Choose between Vbscript (a cut-down version of Visual Basic), JavaScript (a cut-down version of the Java language), PerlScript, Python, Lua, TCL or PHPscript. If you are planning to use PerlScript, Python, TCL or PHPscript you will need to download the script engine (DLL) and possibly other files from their web site(s).

Lua 5.1 is supplied as part of the MUSHclient download. It consists of an extra DLL (Dynamic Link Library) - lua5.1.dll.

The recommended language to use if you do not already have scripts is Lua. For one thing, Lua is automatically supplied with MUSHclient and is thus always available for scripts. Some extra functionality is available exclusively to Lua scripts.

If you install plugins they can also do scripting. The script language used in a plugin can be different from the one used by the "main world".

Enable script

This must be checked to enable the scripting engine.

Active/not active

If you see the word "(active)" next to "Enable script" it means the script engine is currently active.

If you see the words "(not active)" next to "Enable script" it means the script engine is not currently active.

If it possible for the script engine to be active even with "enable script" unchecked, if you have just unchecked it, because the disabling is done when you close the preferences dialog.

Similarly it is possible for the script engine to be inactive, even  with "enable script" checked, because the enabling is done when you close the preferences dialog. Also, the script file may have caused a compile error, which means that the script was not successfully activated.

Script File:

This is optional, however normally if you are using scripting you would specify a script filename. You would type this in using any editor capable of producing ordinary "text" files, for example, NotePad.

As a convention, a Vbscript file would have a suffix of ".VBS", a JavaScript file a suffix of ".JS", a PerlScript file a suffix of ".PL", a Python file a suffix of ".PYS", and a Lua file a suffix of ".LUA".

If you specify a script filename, and check "Enable script" then MUSHclient will attempt to process that file when you close the "world configuration" dialog box. If any errors are detected you will be notified. Note however that some errors (such as "type mismatch", or "wrong number of arguments") are only detected when individual script subroutines are executed, and thus will not appear at this stage.

Browse...

Click on the "browse" button to locate a script file by using the file browsing dialog box.

New...

Click on the "new" button to create a script file by using the file browsing dialog box. If you choose a file name and click OK, then a new, empty script file of that name will be created for you.

Edit Script

By clicking on this button, your script file is opened in your specified editor (the default editor is Notepad).

Choose Editor...

Click on this button to choose a different editor to edit your script files.

Use inbuilt notepad to edit scripts

If checked, MUSHclient's internal notepad is used to edit scripts.

Warn if inactive

If checked, you will get a warning in the output window if a trigger, timer or alias tries to call a script (in the script file) but it cannot, because scripting is disabled, the function is not available, or the script file had a parse error.

Note errors

If checked, errors in scripts will be displayed in the output window (using world.Note) rather than having a dialog-box pop up at an inconvenient time.

Be warned that if the error occurs in "send to script" for a trigger that is "omit from output" then the error message will also be omitted. If such a trigger does not seem to be working, you may want to uncheck this box temporarily to see if there was a script error.

Note Colour:

In the script language you can make "notes" which appear in the output window. You can choose which colour you want the notes to appear in. To make a note, you would say something like:

world.Note "Here is a note"

in your script. The colour is chosen from the world's custom colours pallette.

You can change the colour for notes inside a script by using various script functions, such as world.ColourNote.

World Events

You can put the names for subroutines (functions) that you want called for the various events below. The name must match the name of a function in your world's script file. For example, if you specify "OnWorldOpen" for the "open" event below, then your script should look like this (in Lua):

function OnWorldOpen ()

  Note ("World has been opened")

end -- function OnWorldOpen

Alternatively, if the world event name starts with the "!" character, then the rest of the string is sent to "Execute" - that is, the MUSHclient command processor.

For example, under "Connect" you might have:  !/Sound ("ding.wav")

This would play a sound when you connect (if the script prefix was "/").

Alternatively, you might put the name of an alias there to handle doing multiple things upon connecting. For example:  !connection_alias

Open:

Called when the world file is opened (once per world).

Connect:

Called when the world connects to the MUD. You might use this to send initial commands needed after connection, or to enable/disable triggers etc.

Get Focus:

Called when the world gets the "focus". The focus is obtained when the particular world window becomes the active window (ie. the title bar changes to the active colour).

Lose Focus:

Called when the world loses the focus, as described above.

Disconnect:

Called when the world has been disconnected.

Close:

Called while the world is being closed.

Save:

Called just before the world file is being saved. You can use this event to save internal script variables to MUSHclient variables, so they are saved as well.

MXP...

Click to set extra script functions to be called when MXP is active.

Register DLL

If scripting is not working you can try clicking this to cause the script engine DLL to be "registered" with Windows. You should only need to do this once per PC. It is not necessary to do it for Lua, and is only implemented for VBscript, Jscript and PHP script.

Recompile when script changes:

When a script file changes MUSHclient may detect this (depending on the Operating System version). Select what behaviour you want when this happens:

You can set the scripts to automatically recompile when you edit and save the script file by setting this option to "always".

To ask whether ot not to recompile, set this option to "confirm".

To never recompile, set this option to "never".

Script Prefix:

You can enter one or more characters here which will act as a "script language" prefix. The recommended prefix is the "/" character. If you type the "script prefix" in the command window, then the rest of the command window (which can be multiple lines if you press Ctrl+Enter) is sent to the script engine. For example:

/ Note ("Hi there!")

would display a note in the output window.

An alternative way of entering small test scripts is to use the Immediate scripting window.

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Command

 ConfigureScripting (Sets scripting options)

Dialog

 Immediate

(Help topic: dialog=IDD_PREFS_P17)


Send

When sending a file to a MUD you have the option to prepend or append strings to your file (in other words, put text before and/or after each line, and the entire file).

Note that there will always be a "linefeed" sent at the end of each line, you do not need to send one yourself.

Programming a MUD

If you are writing a program for an LP MUD you might want to start with:

<commands to start up the internal editor>

Then at the start of each line:

<command to insert a line>

Then at the end of the file:

<command to exit from the editor>

Echoing messages

Alternatively, you may wish to echo a message to someone that you heard elsewhere (e.g. from email). In this case you might wish to put, at the start of each line:

say

so that you "say" the contents of the file.

1. Send this at the start of a "send file to world":

This string is sent once, at the start of a "send file" operation. It could be used to enter programming mode on a MUD, if necessary. This string can consist of multiple lines, with "carriage returns" between each line.

2. Send this at the start of each line:

This string is sent at the start of each line from the file. It could contain any special prefix that you need at the start of each line, for example, the word "say ".

3. Send this at the end of each line:

This string is sent at the end of each line from the file

4. Send this at the end of a "send file to world":

This string is sent once, at the end of a "send file" operation. It could be used to exit from programming mode on a MUD, if necessary. This string can consist of multiple lines, with "carriage returns" between each line.

Delay between lines:

You can set a delay of up to 10 seconds between each line of text that is sent to the world. This is designed to give the server time to respond. Time is specified in milliseconds (1000 milliseconds to one second). You should keep this time as short as possible to avoid lengthy delays on doing a send. A reasonable figure might be 100 (1/10 of a second).

Every X lines

This is the number of lines that are sent before the delay (above) is invoked. Thus, you could set it up to delay 2 seconds every 100 lines.

Commented Softcode

This allows you to send commented softcode to a MUSH (MUX, or similar). See the description for "sending and pasting" for more details about that.

Echo to output window

If checked, the file is echoed to the output window, otherwise it is not.

Confirm on each "send file to world"

If checked, you are asked to confirm the above settings each time you paste to a MUD. If unchecked, these options are taken "as is".

See Also ...

Topics

 Commented softcode

 Sending to the world

Command

 ConfigureSendFile (Sets 'send file' options)

Dialog

 Confirm preamble and postamble for pasting or sending file to the world

(Help topic: dialog=IDD_PREFS_P10)


Send to multiple worlds

The message you enter is sent to all selected worlds. This is a quick way of communicating with some or all worlds you are connected to (eg. "say see you tomorrow").

Send to selected worlds:

Select the worlds you want the message to be sent to by clicking, shift-clicking or ctrl-clicking.

Select All

Click to select all worlds.

Select None

Click to select no worlds.

Echo in output window

Check to have the message echoed in the output window of the selected worlds.

Message

Type your message here.

See Also ...

Command

 SendToAllWorlds (Sends a message to all worlds)

(Help topic: dialog=IDD_SEND_TO_ALL)


Special Map Movement

This lets you add special movement commands to the automapper sequence.

Special commands are those not automatically recognised by MUSHclient as commands that move you somewhere.

The standard commands are:

n (north), s (south), e (east), w (west), ne, se, nw, sw, u (up) and d (down)

The directions in brackets are synomyms - either may be used.

Any other "movement" command must be entered via this dialog, or the mapper will not record it.

MUSHclient generates a speedwalk string like this:

(forwards/reverse)

This is consistent with the speedwalk syntax used when doing normal speedwalking. The characters before the "/" are the forwards direction, the characters after the "/" are the reverse direction.

Action:

Enter the "forwards" action - the one you want to take right now.

For example:

@teleport 1234

unlock west

use key

go portal

recall

mount horse

enter

leave

board boat

Reverse:

You can also enter the "reverse" command, which is what you need to do when going back the way you came.

@teleport 3421

lock east

go portal

recall

dismount horse

leave

exit

go shore

Send to MUD

If checked, the forwards command is sent to the MUD. This is the default behaviour, so that the command is recorded (in the mapper) and done immediately, so that you see the effects of it.

If, for some reason, you want to add commands to the mapping sequence, but not actually send them to the MUD, then uncheck this.

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Command

 DoMapperSpecial (Do a non-standard direction command)

Dialog

 Map Comment

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: dialog=IDD_MAP_MOVE)


Spell Check

This shows a misspelt word during the spell-check process.

Misspelt:

This is the word currently being considered. You can edit it in this box and click "Change" to change it to another word - that is, make a manual correction.

Suggestions

This is a list of suggested spellings, based on the "sound" of the original word, arranged in alphabetic order. Choose one and click the "Change" button to accept the suggestion. Or, double-click a suggested word.

Ignore

Ignore the misspelt word once.

Ignore All

Ignore this word this time, and all future times, in this spell-check operation.

To ignore a word forever, click "Add" instead.

Add

Adds this word to the "user" dictionary, so it is always considered correctly spelt.

Change

Change to the word you typed into the edit box, or the currently-selected suggested spelling.

Change All

If you have corrected the word, change all instances of the original spelling, to the new spelling.

Cancel

Cancel the spell-check operation.

See Also ...

Topic

 Spell checker

Command

 SpellCheck (Spell checks the command in the command window)

Dialog

 Global preferences - general options

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: dialog=IDD_SPELLCHECK_DIALOG)


Spell-Check options

Ignore capitalized words (e.g., Canada)

Ignore all-caps words (e.g., ASAP)

Ignore words with numbers (e.g., Win95)

Ignore words with mixed case (e.g., SuperBase)

Ignore domain names (e.g., xyz.com)

Report doubled words (e.g., the the)

Case sensitive

Phonetic suggestions

Typographical suggestions

Suggest split words

Auto correct

Suggestions

Fast but less accurate

Moderately fast and accurate

Slow but accurate

OK

Help

Cancel

Main Dictionary language:

(Help topic: dialog=OPTIONSDLG)


Tab completion defaults

Default Word List

Words below will be checked for first when you press <tab> to complete a word in the command window. Enter each word with a space between them.

After that, MUSHclient will scan backwards through the output window text to find a match.

Lines To Check

Enter the number of lines to scan backwards in the output window. The more lines you have the slower it can be to find a match, and possibly the less relevant a match will be.

Insert Space After Word

If checked, a space will be inserted after the tab-completed word. This is handy if you want to put the completed word in the middle of a sentence.

(Help topic: dialog=IDD_TAB_COMPLETION_DEFAULTS_DLG)


Test command

Enter (or paste) the command you wish to test:

Enter a command.

When you click OK you will be shown what actually gets sent to the world in response to the above command, after aliases, speed walking, command stacking etc. are evaluated.

(Help topic: dialog=IDD_TEST_COMMAND)


Test results

The following would be sent to the world:

This shows what would be sent when you test a command.

(Help topic: dialog=IDD_TEST_RESULT)


Test trigger

Enter (or paste) the trigger you wish to test:

Enter some simulated MUD output.

When you click OK you will be shown what actually gets sent to the world in response to receiving the above text from the world, after all triggers are evaluated.

Ignore triggers that match on colours or styles

If checked, triggers that match on colours or styles will not be tested.

(Help topic: dialog=IDD_TEST_TRIGGER)


Text attributes

Line info...

Click to open a notepad window describing in great detail the text on the selected line (eg. Style runs, colours).

The start of the current selection is:

Use this dialog to see what type of text is under the selection in the output window.

Letter:

This is the letter at the start of the selection.

Text colour:

The colour of the text of the selected letter.

Background colour:

The colour of the background of the selected letter.

Custom colour:

If a custom colour, which one it is.

Bold

If checked, the character is in bold.

Italic

If checked, the character is in italic.

Inverse

If checked, the character is in inverse.

The colour or style HAS been modified by a trigger.

If you see this message, the colour has been modified by a trigger (ie. It is not the original colour).

See Also ...

Command

 TextAttributes (Gets the attributes of the first character of the selection)

(Help topic: dialog=IDD_TEXT_ATTRIBUTES)


Thanks for upgrading MUSHclient!

Welcome to MUSHclient, version X

This screen notifies you that you are using a different version of MUSHclient to before.

It only appears once per version change.

(Help topic: dialog=IDD_WELCOME1)


Timers

Enable Timers

If checked, all timers are enabled (active).

Override with default timers

If checked, next time the world is loaded your timers are replaced with the default ones. See the help topic on "defaults" for more details.

Add...

Click to add a timer.

Edit...

Click to edit an existing timer.

Remove

Click to remove one or more selected timers from the list.

Find...

Click to find a timer based on its contents.

Find Next

Click to repeat the next find (find another one that matches).

Load...

Click to load timers from disk.

Save...

Click to save selected timers to disk.

Reset All Timers

Click to reset all timers. This means that timers that fire after a certain interval will start counting again from zero.

Copy

Click to copy the selected timer(s) to the clipboard in XML format.

Paste

Click to paste the clipboard into the timer list. The timers must be in XML format (such as produced by the Copy button). Only timers will be pasted, if there are other types on the clipboard.

Copy and paste is intended to allow you to get/put timers onto the Forum, or exchange them between worlds or with other MUSHclient users.

Tree View

Check to show a "tree" view of the items. Leave unchecked to show a "list" view. In tree view only one item can be selected at once, however you can select an entire group for the purpose of copying the group to the clipboard, or deleting it.

In tree view items are sorted into groups.

Filter by:

Check to filter the visible items by the function "filter". Click on the button labelled "..." next to the "filter by" checkbox to enter the code for the scripted filter function. The filter function must be written in Lua and have a function named "filter" in the script, taking two arguments which are the name (label) of the timer, and a table of values corresponding to the various settings for it. For example, to show only timers that do "send to script":

function filter (name, timer)

  return timer.send_to == sendto.script

end -- filter

You can use the various values for this timer to work out whether or not you want this particular one to be shown in the list (for example, if it sends to script). If the function returns the boolean value "false" then the item is not shown, otherwise it is shown in the list.

The filter script is saved in the world file, so you can use it again next time, however the filter flag is not remembered. You must explicitly enable it each time you want to filter the list.

The various fields in the timer table are documented here:

http://www.gammon.com.au/forum/?id=7123

In addition, some fields calculated at runtime are:

"invocation_count"  // GetTimerInfo  (9)

"times_fired"       // GetTimerInfo  (10)

"when_fired"        // GetTimerInfo  (11) *

"temporary"         // GetTimerInfo  (14)

"included"          // GetTimerInfo  (18)

"script_valid"      // GetTimerInfo  (26)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Command

 ConfigureTimers (Define timers)

Dialog

 Edit timer

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: dialog=IDD_PREFS_P16)


Tip of the Day

Shows a helpful tip.

Show Tips on StartUp

If checked, you will see a tip every time MUSHclient start up.

Next Tip

Click for the next tip.

Close

Click to stop viewing tips.

See Also ...

Command

 TipOfTheDay (Shows the Tip of the Day)

(Help topic: dialog=IDD_TIP)


Trigger configuration list

Enable Triggers

If checked, all triggers are enabled (active).

Enable Trigger Sounds

If checked, sounds which are specified for each trigger are played when they fire. If unchecked the triggers become silent. However this does not apply to "scripted" sounds. That is, if a trigger calls a script and script calls the Sound function, that will still play.

Override with default triggers

If checked, next time the world is loaded your triggers are replaced with the default ones. See the help topic on "defaults" for more details.

Add...

Click to add a trigger.

Edit...

Click to edit an existing trigger.

Remove

Click to remove one or more selected triggers from the list.

Find...

Click to find a trigger based on its contents.

Find Next

Click to repeat the next find (find another one that matches).

Load...

Click to load triggers from disk.

Save...

Click to save selected triggers to disk.

Move Up

Click to move the selected trigger up the list (in other words, lower its sequence number).

Move Down

Click to move the selected trigger down the list (in other words, raise its sequence number).

Copy

Click to copy the selected trigger(es) to the clipboard in XML format.

Paste

Click to paste the clipboard into the trigger list. The triggers must be in XML format (such as produced by the Copy button). Only triggers will be pasted, if there are other types on the clipboard.

Copy and paste is intended to allow you to get/put triggers onto the Forum, or exchange them between worlds or with other MUSHclient users.

Tree View

Check to show a "tree" view of the items. Leave unchecked to show a "list" view. In tree view only one item can be selected at once, however you can select an entire group for the purpose of copying the group to the clipboard, or deleting it.

In tree view items are sorted into groups. Inside the group the items are shown in sequence order.

Filter by:

Check to filter the visible items by the function "filter". Click on the button labelled "..." next to the "filter by" checkbox to enter the code for the scripted filter function. The filter function must be written in Lua and have a function named "filter" in the script, taking two arguments which are the name (label) of the trigger, and a table of values corresponding to the various settings for it.  For example, to show only triggers that do "send to script":

function filter (name, trigger)

  return trigger.send_to == sendto.script

end -- filter

You can use the various values for this trigger to work out whether or not you want this particular one to be shown in the list (for example, if it sends to script). If the function returns the boolean value "false" then the item is not shown, otherwise it is shown in the list.

The filter script is saved in the world file, so you can use it again next time, however the filter flag is not remembered. You must explicitly enable it each time you want to filter the list.

The various fields in the trigger table are documented here:

http://www.gammon.com.au/forum/?id=7123

In addition, some fields calculated at runtime are:

"invocation_count"  // GetTriggerInfo  (20)

"times_matched"     // GetTriggerInfo  (21)

"when_matched"      // GetTriggerInfo  (22) *

"temporary"         // GetTriggerInfo  (23)

"included"          // GetTriggerInfo  (24)

"match_count"       // GetTriggerInfo  (31) *

"last_match"        // GetTriggerInfo  (32) *

"script_valid"      // GetTriggerInfo  (34)

"execution_error"   // GetTriggerInfo  (35) *

"execution_time"    // GetTriggerInfo  (37) *

"match_attempts"    // GetTriggerInfo  (38) *

Fields marked * may not be present (ie. be nil) under some circumstances (eg. regular expression failure).

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Command

 ConfigureTriggers (Define triggers)

Dialog

 Edit trigger

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: dialog=IDD_PREFS_P8)


Variables configuration (list)

Add...

Click to add a variable.

Edit...

Click to edit an existing variable.

Remove

Click to remove one or more selected variables from the list.

Find...

Click to find a variable based on its name or contents.

Find Next

Click to repeat the next find (find another one that matches).

Load...

Click to load variables from disk.

Save...

Click to save selected variables to disk.

Copy

Click to copy the selected variable(s) to the clipboard in XML format.

Paste

Click to paste the clipboard into the variables list. The variables must be in XML format (such as produced by the Copy button). Only variables will be pasted, if there are other types on the clipboard.

Copy and paste is intended to allow you to get/put variables onto the Forum, or exchange them between worlds or with other MUSHclient users.

Filter by:

Check to filter the visible items by the function "filter". Click on the button labelled "..." next to the "filter by" checkbox to enter the code for the scripted filter function. The filter function must be written in Lua and have a function named "filter" in the script, taking two arguments which are the name of the variable, and a table of values corresponding to the various settings for it. For example, to show only variables that start with "mxp_":

function filter (name, variable)

  return string.find (name, "^mxp_") ~= nil

end -- filter

You can use variable.contents to find out the contents if that variable if needed, and work out whether to show it or not. If the function returns the boolean value "false" then the item is not shown, otherwise it is shown in the list.

The filter script is saved in the world file, so you can use it again next time, however the filter flag is not remembered. You must explicitly enable it each time you want to filter the list.

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Command

 ConfigureVariables (Sets program variables)

Dialog

 Edit variable

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: dialog=IDD_PREFS_P18)


Welcome to MUSHclient!

Welcome to MUSHclient!

This is the welcome screen for new users of MUSHclient.

(Help topic: dialog=IDD_WELCOME)


Windows Sockets information

Version:

The version of WinSock (Windows Socket Library) in use.

High version:

The highest version supported by the WinSock DLL.

Description:

Description of the version.

Status:

DLL status.

Max sockets:

Maximum sockets supported/

Host name:

Name of this PC.

Our address(es):

The IP address(es) of this PC.

See Also ...

Topic

 Information

Command

 WindowsSocketInformation (Information about the version of Winsock in use)

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: dialog=IDD_WINSOCK_INFO)


World name and TCP/IP address

World Name:

This can be anything you like, it is there to help you identify the MUD on screen displays, alert boxes and so on. As an example, enter: "Realms of Despair".

MUD address and port

You connect to a MUD via an address and "port number". Enter them below.

TCP/IP Address:

This is the Internet address of the game's server. This will be the number OR name given on MUSH distribution lists. In the case of Realms of Despair you could enter:

realmsofdespair.com

or

216.251.47.10  (this number may change)

Port Number:

This is the port that the MUSH server is listening for new connections on. In the case of PennMUSH-style MUSHes it is usually 4201, but could be some other number. Diku-style MUDs often use port 4000. This number is always advised next to the MUSH address of distribution lists.

Example

You read about a MUD: Realms of Despair - realmsofdespair.com:4000

This tells you the MUD name (Realms of Despair), the address (realmsofdespair.com) and the port number (4000).

Clear Cached IP

Click this to clear MUSHclient's internal "cache" of the MUD TCP/IP address. You may need to do this if the MUD changes addresses frequently, as MUSHclient saves time by remembering the name-to-IP address lookup.

Proxy Server

If you are using a proxy server (Socks 4 or Socks 5 protocol) then choose the appropriate protocol from the combo-box, otherwise select "none".

Socks 5 is the more recent protocol and should be used in preference to Socks 4.

Lists of proxy servers can be found by searching the Internet. We suggest using keywords like "proxy server socks" in your search engine. Some are free, some you pay for.

Address:

Enter the address of the proxy server (name or dotted-number). This is the address of the proxy server, not the MUD.

Port:

Enter the port for connecting to the proxy server. Typical port numbers for proxy servers are 1050 or 1080, however consult the documentation for your particular server.

Proxy server password...

If your proxy server requires a name and password (Socks 5 only) click on this to enter them.

Save World Automatically On Close

If this is checked then the "world" file is automatically saved (if you have changed anything) when you close the world. This is useful if you definitely want to save changes you have made to your world (eg. Notes, Variables) after every session.

MUD lists

A link to a page on our website that lists places you can look to find MUDs to play.

Bug report URL

A link to a page on our website for reporting bugs and suggestions.

See Also ...

Commands

 ConfigureMudaddress (Set name, TCP/IP address and port of the MUD)

 Preferences (Set world details (name, font, colour etc.))

Dialog

 Connecting

(Help topic: dialog=IDD_PREFS_P1)


About

Summary

Display program information, version number and copyright

Details

Shows program information, including version number.

Menu

Help -> About MUSHclient...

Example of script call

world.DoCommand "About"

See Also ...

Dialog

 About MUSHclient

(Help topic: command=About)


ActivateInputArea

Summary

Makes the command view active

Details

Moves the focus to the command window.

Menu

Input -> Activate Input Area

Example of script call

world.DoCommand "ActivateInputArea"

(Help topic: command=ActivateInputArea)


ActivityList

Summary

Shows list of windows with new output

Details

Shows the activity list window.

Menu

Display -> Activity List

Keyboard Shortcut

Shift+Ctrl+L

Example of script call

world.DoCommand "ActivityList"

(Help topic: command=ActivityList)


ActivityToolbar

Summary

Show or hide the activity toolbar

Details

Shows the activity toolbar - with one button for each of the first 10 worlds open.

Menu

View -> Activity Toolbar

Example of script call

world.DoCommand "ActivityToolbar"

(Help topic: command=ActivityToolbar)


ActivityViewCloseWorld

Summary

Close the selected world

Menu

File -> Close World

Example of script call

world.DoCommand "ActivityViewCloseWorld"

(Help topic: command=ActivityViewCloseWorld)


ActivityViewSaveWorld

Summary

Save the selected world details

Menu

File -> Save World Details

Example of script call

world.DoCommand "ActivityViewSaveWorld"

(Help topic: command=ActivityViewSaveWorld)


ActivityViewSaveWorldAs

Summary

Saves the selected world under another file name

Menu

File -> Save World Details As...

Example of script call

world.DoCommand "ActivityViewSaveWorldAs"

(Help topic: command=ActivityViewSaveWorldAs)


AltA

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+A

Example of script call

world.DoCommand "AltA"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltA)


AltB

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+B

Example of script call

world.DoCommand "AltB"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltB)


AltDownArrow

Summary

Recalls partial command - downwards

Details

If the option "alt+arrow traverses command history" is set, moves downwards to the next matching command.

Otherwise, selects the next command in the command history.

Keyboard Shortcut

Alt+Down

Example of script call

world.DoCommand "AltDownArrow"

(Help topic: command=AltDownArrow)


AltJ

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+J

Example of script call

world.DoCommand "AltJ"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltJ)


AltK

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+K

Example of script call

world.DoCommand "AltK"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltK)


AltL

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+L

Example of script call

world.DoCommand "AltL"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltL)


AltM

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+M

Example of script call

world.DoCommand "AltM"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltM)


AltN

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+N

Example of script call

world.DoCommand "AltN"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltN)


AltO

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+O

Example of script call

world.DoCommand "AltO"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltO)


AltP

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+P

Example of script call

world.DoCommand "AltP"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltP)


AltQ

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+Q

Example of script call

world.DoCommand "AltQ"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltQ)


AltR

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+R

Example of script call

world.DoCommand "AltR"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltR)


AltS

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+S

Example of script call

world.DoCommand "AltS"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltS)


AltT

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+T

Example of script call

world.DoCommand "AltT"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltT)


AltU

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+U

Example of script call

world.DoCommand "AltU"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltU)


AltUpArrow

Summary

Recalls partial command - upwards

Details

If the option "alt+arrow traverses command history" is set, moves upwards to the next matching command.

Otherwise, selects the previous command in the command history.

Keyboard Shortcut

Alt+Up

Example of script call

world.DoCommand "AltUpArrow"

(Help topic: command=AltUpArrow)


AltV

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+V

Example of script call

world.DoCommand "AltV"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltV)


AltX

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+X

Example of script call

world.DoCommand "AltX"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltX)


AltY

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+Y

Example of script call

world.DoCommand "AltY"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltY)


AltZ

Summary

Executes a user-defined macro.

Keyboard Shortcut

Alt+Z

Example of script call

world.DoCommand "AltZ"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=AltZ)


AlwaysOnTop

Summary

Keeps MUSHclient windows on top of other windows

Details

Sets the "always on top" flag so that MUSHclient will always be on top of other application windows, even if the program does not currently have the focus.

Menu

View -> Always On Top

Example of script call

world.DoCommand "AlwaysOnTop"

(Help topic: command=AlwaysOnTop)


ArrangeIcons

Summary

Arrange icons at the bottom of the window

Details

Arranges the icons (for minimised windows in the main frame view) neatly.

Menu

Window -> Arrange Icons

Example of script call

world.DoCommand "ArrangeIcons"

(Help topic: command=ArrangeIcons)


ASCIIart

Summary

Generate ASCII art

Details

The "ASCII Art" window lets you type in up to 60 characters of text, and have them converted into "big letters", like this:

 __  __ _   _ ____  _   _      _ _            _

|  \/  | | | / ___|| | | | ___| (_) ___ _ __ | |_

| |\/| | | | \___ \| |_| |/ __| | |/ _ \ '_ \| __|

| |  | | |_| |___) |  _  | (__| | |  __/ | | | |_

|_|  |_|\___/|____/|_| |_|\___|_|_|\___|_| |_|\__|

Menu

Edit -> ASCII Art...

Keyboard Shortcut

Shift+Ctrl+A

Example of script call

world.DoCommand "ASCIIart"

See Also ...

Topic

 Notepad

Dialog

 ASCII Art

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=ASCIIart)


AutoConnect

Summary

Automatically connect to worlds when opening them

Details

Toggles the "auto-connect" flag.

If active, when you open the world file for a new world, MUSHclient will attempt to connect to it immediately.

If inactive, you must connect manually. One easy way of doing this is simply to hit <enter> in the command window.

Menu

Connection -> Auto Connect

Example of script call

world.DoCommand "AutoConnect"

(Help topic: command=AutoConnect)


AutoSay

Summary

Whatever you type is "said" in the game

Details

Toggles the "auto-say" flag.

If active, what you type is prefixed with the "auto-say" string and sent to the MUD. (eg. "say hello there").

You can configure the auto-say string to be something useful, like "say", "tell", "chat" and so on.

Menu

Input -> Auto Say

Keyboard Shortcut

Shift+Ctrl+A

Example of script call

world.DoCommand "AutoSay"

See Also ...

Dialog

 Auto Say

(Help topic: command=AutoSay)


Base64Decode

Summary

Decodes Base-64 coding

Details

This converts a Base64-encoded string to its original value.

Menu

Convert -> Base64 Decode

Keyboard Shortcut

Ctrl+Alt+D

Example of script call

world.DoCommand "Base64Decode"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=Base64Decode)


Base64Encode

Summary

Encodes text into Base-64 coding

Details

This takes a string and encodes it using the Base64 encoding system.

Menu

Convert -> Base64 Encode

Keyboard Shortcut

Ctrl+Alt+E

Example of script call

world.DoCommand "Base64Encode"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=Base64Encode)


BookmarkSelection

Summary

Toggles a bookmark at the selected line

Details

Toggles the "bookmarked" flag for the selected line. You must select some text on a line for this to work (any text). You can then use "go to bookmark" (Ctrl+B) to go to bookmarked lines.

Menu

Display -> Bookmark Selection

Keyboard Shortcut

Shift+Ctrl+B

Example of script call

world.DoCommand "BookmarkSelection"

(Help topic: command=BookmarkSelection)


BugReports

Summary

Submit a bug report or suggestion (via the Internet)

Details

Invokes the appropriate web page for submitting bug reports.

Menu

Help -> Bug Reports...

Example of script call

world.DoCommand "BugReports"

(Help topic: command=BugReports)


CascadeWindows

Summary

Arrange windows so they overlap

Details

Cascades open windows.

Menu

Window -> Cascade

Example of script call

world.DoCommand "CascadeWindows"

(Help topic: command=CascadeWindows)


ChatSessions

Summary

Show all chat sessions for this world

Menu

Game -> Chat Sessions

Keyboard Shortcut

Shift+Ctrl+Alt+C

Example of script call

world.DoCommand "ChatSessions"

See Also ...

Topics

 Chat system

 Getting started

Dialog

 Chat sessions

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: command=ChatSessions)


ClearCommandHistory

Summary

Clears command history

Menu

Input -> Clear Command History...

Keyboard Shortcut

Shift+Ctrl+D

Example of script call

world.DoCommand "ClearCommandHistory"

(Help topic: command=ClearCommandHistory)


ClearOutput

Summary

Removes all output from the output window

Menu

Display -> Clear Output Buffer...

Keyboard Shortcut

Shift+Ctrl+C

Example of script call

world.DoCommand "ClearOutput"

(Help topic: command=ClearOutput)


Close

Summary

Close the active world

Menu

File -> Close World

Example of script call

world.DoCommand "Close"

(Help topic: command=Close)


CloseAllNotepadWindows

Summary

Closes all open notepad windows

Menu

Window -> Close All Notepad Windows

Example of script call

world.DoCommand "CloseAllNotepadWindows"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=CloseAllNotepadWindows)


ColourPicker

Summary

Choose a colour from a list

Menu

Edit -> Colour Picker

Keyboard Shortcut

Ctrl+Alt+P

Example of script call

world.DoCommand "ColourPicker"

See Also ...

Dialog

 Colour picker

(Help topic: command=ColourPicker)


CommandEnd

Summary

Go to end of command window

Keyboard Shortcut

Alt+End

Example of script call

world.DoCommand "CommandEnd"

(Help topic: command=CommandEnd)


CommandHistory

Summary

Shows previous commands entered

Menu

Input -> Command History...

Keyboard Shortcut

Ctrl+H

Example of script call

world.DoCommand "CommandHistory"

(Help topic: command=CommandHistory)


CommandHome

Summary

Go to start of command window

Keyboard Shortcut

Alt+Home

Example of script call

world.DoCommand "CommandHome"

(Help topic: command=CommandHome)


CompleteFunction

Summary

Invokes a menu of function names that match a partially typed one

Details

Show a dialog that lets you complete a partially-typed inbuilt function name.

Menu

Edit -> Complete Function Name

Keyboard Shortcut

Ctrl+Space

Example of script call

world.DoCommand "CompleteFunction"

See Also ...

Topic

 Notepad

Dialog

 Complete Function Name

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=CompleteFunction)


ConfigureAliases

Summary

Define aliases

Menu

Configure -> Aliases...

Keyboard Shortcut

Shift+Ctrl+9

Example of script call

world.DoCommand "ConfigureAliases"

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Dialog

 Alias configuration (list)

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: command=ConfigureAliases)


ConfigureAutosay

Summary

Sets auto-say options

Menu

Configure -> Auto say...

Keyboard Shortcut

Shift+Ctrl+3

Example of script call

world.DoCommand "ConfigureAutosay"

See Also ...

Dialog

 Auto Say

(Help topic: command=ConfigureAutosay)


ConfigureChat

Summary

Configure chat settings

Menu

Configure -> Chat...

Example of script call

world.DoCommand "ConfigureChat"

See Also ...

Topics

 Chat system

 Getting started

Dialog

 Chat

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: command=ConfigureChat)


ConfigureColours

Summary

Sets output colours

Menu

Configure -> ANSI Colours...

Keyboard Shortcut

Alt+6

Example of script call

world.DoCommand "ConfigureColours"

See Also ...

Dialog

 ANSI Colour

(Help topic: command=ConfigureColours)


ConfigureCommands

Summary

Sets input options

Menu

Configure -> Commands...

Keyboard Shortcut

Alt+0

Example of script call

world.DoCommand "ConfigureCommands"

See Also ...

Dialog

 Commands

(Help topic: command=ConfigureCommands)


ConfigureCustomColours

Summary

Custom Colours

Menu

Configure -> Custom Colours...

Keyboard Shortcut

Alt+8

Example of script call

world.DoCommand "ConfigureCustomColours"

See Also ...

Dialog

 Custom Colour

(Help topic: command=ConfigureCustomColours)


ConfigureHighlighting

Summary

Options for highlighting incoming text

Menu

Configure -> Sounds...

Keyboard Shortcut

Alt+7

Example of script call

world.DoCommand "ConfigureHighlighting"

(Help topic: command=ConfigureHighlighting)


ConfigureKeypad

Summary

Sets numeric keypad options

Menu

Configure -> Keypad...

Keyboard Shortcut

Shift+Ctrl+1

Example of script call

world.DoCommand "ConfigureKeypad"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=ConfigureKeypad)


ConfigureLogging

Summary

Sets logging options

Menu

Configure -> Logging...

Keyboard Shortcut

Alt+3

Example of script call

world.DoCommand "ConfigureLogging"

See Also ...

Topic

 Logging

Dialog

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: command=ConfigureLogging)


ConfigureMacros

Summary

Sets macro options

Menu

Configure -> Macros...

Keyboard Shortcut

Shift+Ctrl+2

Example of script call

world.DoCommand "ConfigureMacros"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=ConfigureMacros)


ConfigureMudaddress

Summary

Set name, TCP/IP address and port of the MUD

Menu

Configure -> MUD Name/IP address...

Keyboard Shortcut

Alt+1

Example of script call

world.DoCommand "ConfigureMudaddress"

See Also ...

Dialog

 World name and TCP/IP address

(Help topic: command=ConfigureMudaddress)


ConfigureMxpPueblo

Summary

MXP and Pueblo configuration

Menu

Configure -> MXP / Pueblo...

Keyboard Shortcut

Ctrl+Alt+U

Example of script call

world.DoCommand "ConfigureMxpPueblo"

See Also ...

Dialog

 MXP / Pueblo

(Help topic: command=ConfigureMxpPueblo)


ConfigureNameAndPassword

Summary

Sets character name and password

Menu

Configure -> Connecting...

Keyboard Shortcut

Alt+2

Example of script call

world.DoCommand "ConfigureNameAndPassword"

See Also ...

Dialog

 Connecting

(Help topic: command=ConfigureNameAndPassword)


ConfigureNotes

Summary

Set notes about this world

Menu

Configure -> Notes...

Keyboard Shortcut

Alt+4

Example of script call

world.DoCommand "ConfigureNotes"

See Also ...

Dialog

 Notes

(Help topic: command=ConfigureNotes)


ConfigureOutput

Summary

Sets output options

Menu

Configure -> Output...

Keyboard Shortcut

Alt+5

Example of script call

world.DoCommand "ConfigureOutput"

See Also ...

Dialog

 Output

(Help topic: command=ConfigureOutput)


ConfigurePasteToWorld

Summary

Sets 'paste to world' options

Menu

Configure -> Paste to world...

Keyboard Shortcut

Shift+Ctrl+4

Example of script call

world.DoCommand "ConfigurePasteToWorld"

See Also ...

Dialog

 Paste

(Help topic: command=ConfigurePasteToWorld)


ConfigurePrinting

Summary

Printing options

Menu

Configure -> Printing...

Keyboard Shortcut

Alt+9

Example of script call

world.DoCommand "ConfigurePrinting"

See Also ...

Dialog

 Printing

(Help topic: command=ConfigurePrinting)


ConfigureScripting

Summary

Sets scripting options

Menu

Configure -> Scripting...

Keyboard Shortcut

Shift+Ctrl+6

Example of script call

world.DoCommand "ConfigureScripting"

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Scripts

(Help topic: command=ConfigureScripting)


ConfigureSendFile

Summary

Sets 'send file' options

Menu

Configure -> Send file...

Keyboard Shortcut

Shift+Ctrl+5

Example of script call

world.DoCommand "ConfigureSendFile"

See Also ...

Topics

 Commented softcode

 Sending to the world

Dialog

 Send

(Help topic: command=ConfigureSendFile)


ConfigureTimers

Summary

Define timers

Menu

Configure -> Timers...

Keyboard Shortcut

Shift+Ctrl+0

Example of script call

world.DoCommand "ConfigureTimers"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Dialog

 Edit timer

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: command=ConfigureTimers)


ConfigureTriggers

Summary

Define triggers

Menu

Configure -> Triggers...

Keyboard Shortcut

Shift+Ctrl+8

Example of script call

world.DoCommand "ConfigureTriggers"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Dialog

 Trigger configuration list

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: command=ConfigureTriggers)


ConfigureVariables

Summary

Sets program variables

Menu

Configure -> Variables...

Keyboard Shortcut

Shift+Ctrl+7

Example of script call

world.DoCommand "ConfigureVariables"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: command=ConfigureVariables)


Connect

Summary

Establishes a connection to this world

Menu

Connection -> Connect

Keyboard Shortcut

Ctrl+K

Example of script call

world.DoCommand "Connect"

(Help topic: command=Connect)


ConnectToAllOpenWorlds

Summary

Connects to all opened worlds that are not connected yet

Menu

Connection -> Connect To All Open Worlds

Keyboard Shortcut

Ctrl+Alt+K

Example of script call

world.DoCommand "ConnectToAllOpenWorlds"

(Help topic: command=ConnectToAllOpenWorlds)


ConnectToWorldsInStartupList

Summary

Connects to worlds in startup list that are not connected

Menu

Connection -> Connect To Worlds In Startup List

Example of script call

world.DoCommand "ConnectToWorldsInStartupList"

(Help topic: command=ConnectToWorldsInStartupList)


Connect_Or_Reconnect

Summary

Connect or Disconnect from current world

Keyboard Shortcut

Shift+Ctrl+K

Example of script call

world.DoCommand "Connect_Or_Reconnect"

(Help topic: command=Connect_Or_Reconnect)


ContextHelp

Summary

Display help for clicked on buttons, menus and windows

Keyboard Shortcut

Shift+F1

Example of script call

world.DoCommand "ContextHelp"

(Help topic: command=ContextHelp)


ConvertForumCodes

Summary

Converts text on the clipboard for use in the forum

Details

If the clipboard contains text, it is replaced with "forum codes" quoted, namely:

[ becomes \[

] becomes \]

\ becomes \\

You will be presented with a dialog box to confirm the change, in case you accidentally hit the accelerator key, the dialog box states the number of changes made.

Menu

Edit -> Convert Clipboard Forum Codes

Keyboard Shortcut

Shift + Ctrl + Alt + Q

Example of script call

world.DoCommand "ConvertForumCodes"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=ConvertForumCodes)


ConvertHTMLspecial

Summary

Converts special HTML characters, eg. < to &lt;

Menu

Convert -> Convert HTML special

Keyboard Shortcut

Shift+Ctrl+H

Example of script call

world.DoCommand "ConvertHTMLspecial"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=ConvertHTMLspecial)


Copy

Summary

Copy the selection and put it on the Clipboard

Menu

Edit -> Copy

Keyboard Shortcut

Ctrl+Insert

Example of script call

world.DoCommand "Copy"

(Help topic: command=Copy)


CopyAsHTML

Summary

Copies the selected text as HTML

Menu

Edit -> Copy as HTML

Keyboard Shortcut

Ctrl+Alt+C

Example of script call

world.DoCommand "CopyAsHTML"

(Help topic: command=CopyAsHTML)


CtrlKeypad0

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad0

Example of script call

world.DoCommand "CtrlKeypad0"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad0)


CtrlKeypad1

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad1

Example of script call

world.DoCommand "CtrlKeypad1"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad1)


CtrlKeypad2

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad2

Example of script call

world.DoCommand "CtrlKeypad2"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad2)


CtrlKeypad3

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad3

Example of script call

world.DoCommand "CtrlKeypad3"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad3)


CtrlKeypad4

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad4

Example of script call

world.DoCommand "CtrlKeypad4"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad4)


CtrlKeypad5

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad5

Example of script call

world.DoCommand "CtrlKeypad5"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad5)


CtrlKeypad6

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad6

Example of script call

world.DoCommand "CtrlKeypad6"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad6)


CtrlKeypad7

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad7

Example of script call

world.DoCommand "CtrlKeypad7"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad7)


CtrlKeypad8

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad8

Example of script call

world.DoCommand "CtrlKeypad8"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad8)


CtrlKeypad9

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Numpad9

Example of script call

world.DoCommand "CtrlKeypad9"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypad9)


CtrlKeypadDash

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Subtract

Example of script call

world.DoCommand "CtrlKeypadDash"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypadDash)


CtrlKeypadDot

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Decimal

Example of script call

world.DoCommand "CtrlKeypadDot"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypadDot)


CtrlKeypadPlus

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Add

Example of script call

world.DoCommand "CtrlKeypadPlus"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypadPlus)


CtrlKeypadSlash

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Divide

Example of script call

world.DoCommand "CtrlKeypadSlash"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypadSlash)


CtrlKeypadStar

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Ctrl+Multiply

Example of script call

world.DoCommand "CtrlKeypadStar"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=CtrlKeypadStar)


CtrlN

Summary

New world

Keyboard Shortcut

Ctrl+N

Example of script call

world.DoCommand "CtrlN"

(Help topic: command=CtrlN)


Cut

Summary

Cut the selection and put it on the Clipboard

Menu

Edit -> Cut

Keyboard Shortcut

Ctrl+X

Example of script call

world.DoCommand "Cut"

(Help topic: command=Cut)


DebugIncomingPackets

Summary

Shows debug information of text to/from the world

Menu

Edit -> Debug Packets

Keyboard Shortcut

Shift+Ctrl+F11

Example of script call

world.DoCommand "DebugIncomingPackets"

(Help topic: command=DebugIncomingPackets)


DebugWorldInput

Summary

Debug world input

Keyboard Shortcut

Shift+Ctrl+F12

Example of script call

world.DoCommand "DebugWorldInput"

(Help topic: command=DebugWorldInput)


DiscardQueuedCommands

Summary

Discards queued speed-walking commands

Menu

Input -> Discard Queued Commands

Keyboard Shortcut

Ctrl+D

Example of script call

world.DoCommand "DiscardQueuedCommands"

(Help topic: command=DiscardQueuedCommands)


Disconnect

Summary

Disconnects from this world, or stops attempting to connect

Menu

Connection -> Disconnect

Example of script call

world.DoCommand "Disconnect"

(Help topic: command=Disconnect)


DoMapperComment

Summary

Sends comment to auto-mapper

Menu

Game -> Add Mapper Comment...

Keyboard Shortcut

Shift+Ctrl+Alt+D

Example of script call

world.DoCommand "DoMapperComment"

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Dialog

 Map Comment

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: command=DoMapperComment)


DoMapperSpecial

Summary

Do a non-standard direction command

Menu

Game -> Do Mapper Special...

Keyboard Shortcut

Ctrl+Alt+D

Example of script call

world.DoCommand "DoMapperSpecial"

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Dialog

 Special Map Movement

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: command=DoMapperSpecial)


DosToMac

Summary

Converts selection from DOS text to Mac text

Menu

Convert -> DOS To Mac

Example of script call

world.DoCommand "DosToMac"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=DosToMac)


DosToUnix

Summary

Converts selection from DOS text to Unix text

Menu

Convert -> DOS To Unix

Example of script call

world.DoCommand "DosToUnix"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=DosToUnix)


East

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+Ctrl+E

Example of script call

world.DoCommand "East"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=East)


EditScriptFile

Summary

Edits the current script file

Menu

Game -> Edit Script File...

Keyboard Shortcut

Shift+Ctrl+H

Example of script call

world.DoCommand "EditScriptFile"

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

(Help topic: command=EditScriptFile)


End

Summary

Goes to end of view

Menu

Display -> End

Keyboard Shortcut

Ctrl+End

Example of script call

world.DoCommand "End"

(Help topic: command=End)


Examine

Summary

Examine (thing)

Details

Not implemented any more.

Keyboard Shortcut

Ctrl+E

Example of script call

world.DoCommand "Examine"

(Help topic: command=Examine)


ExitClient

Summary

Quit the application; prompts to save documents

Menu

File -> Exit

Example of script call

world.DoCommand "ExitClient"

(Help topic: command=ExitClient)


Find

Summary

Finds data in the display area

Menu

Display -> Find...

Keyboard Shortcut

Ctrl+F

Example of script call

world.DoCommand "Find"

(Help topic: command=Find)


FindAgain

Summary

Repeats the last find

Menu

Display -> Find Again

Keyboard Shortcut

Shift+Ctrl+F

Example of script call

world.DoCommand "FindAgain"

(Help topic: command=FindAgain)


FindNextNotepad

Summary

Find Next

Menu

Search -> Find Next

Keyboard Shortcut

F3

Example of script call

world.DoCommand "FindNextNotepad"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=FindNextNotepad)


FindNotepad

Summary

Find

Menu

Search -> Find...

Keyboard Shortcut

Ctrl+F

Example of script call

world.DoCommand "FindNotepad"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=FindNotepad)


FlipToNotepad

Summary

Flips to related world window

Menu

Edit -> Flip To Notepad

Keyboard Shortcut

Ctrl+Alt+Space

Example of script call

world.DoCommand "FlipToNotepad"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=FlipToNotepad)


Forum

Summary

Goes to the MUSHclient forum on the Internet

Menu

Help -> Forum...

Keyboard Shortcut

Shift+Ctrl+Alt+F

Example of script call

world.DoCommand "Forum"

(Help topic: command=Forum)


FreezeOutput

Summary

Stops auto scroll when messages arrive

Menu

Display -> Pause Output

Keyboard Shortcut

Ctrl+Space

Example of script call

world.DoCommand "FreezeOutput"

(Help topic: command=FreezeOutput)


FullScreenMode

Summary

Uses the full screen area

Menu

View -> Full Screen Mode

Keyboard Shortcut

Ctrl+Alt+F

Example of script call

world.DoCommand "FullScreenMode"

(Help topic: command=FullScreenMode)


FunctionList

Summary

Shows a list of all scripting functions

Details

Shows a dialog box listing all script functions, where you can choose one from the list and show the Help file information about it.

Menu

Game -> Functions List

Keyboard Shortcut

Ctrl+Alt+Shift+L

Example of script call

world.DoCommand "FunctionList"

See Also ...

Topics

 Scripting

 Utilities

Dialog

 Functions

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=FunctionList)


FunctionsWebPage

Summary

Goes to web page which defines MUSHclient functions

Menu

Help -> Functions Web Page ...

Keyboard Shortcut

Shift+Ctrl+Alt+L

Example of script call

world.DoCommand "FunctionsWebPage"

(Help topic: command=FunctionsWebPage)


GenerateCharacterName

Summary

Generates a random MUD character name

Menu

Edit -> Generate Character Name...

Keyboard Shortcut

Ctrl+Alt+N

Example of script call

world.DoCommand "GenerateCharacterName"

See Also ...

Topics

 Scripting

 Utilities

Dialog

 Name generator

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=GenerateCharacterName)


GenerateUniqueID

Summary

Generates a 24-character hashed unique string

Menu

Edit -> Generate Unique ID

Example of script call

world.DoCommand "GenerateUniqueID"

See Also ...

Topics

 Scripting

 Utilities

Dialog

 Generate Unique ID

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=GenerateUniqueID)


GettingStarted

Summary

Help on getting started with MUSHclient

Details

Click on the links below to find out more about getting started with MUSHclient.

Menu

Help -> Getting Started...

Example of script call

world.DoCommand "GettingStarted"

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Getting started

 Program features

 Speed walking

 Timers

 Triggers

Dialog

 Quick Connect

(Help topic: command=GettingStarted)


GlobalPreferences

Summary

Global program preferences

Menu

File -> Global Preferences...

Keyboard Shortcut

Ctrl+Alt+G

Example of script call

world.DoCommand "GlobalPreferences"

See Also ...

Dialog

 Global preferences - world lists and directories

(Help topic: command=GlobalPreferences)


GlobalReplace

Summary

Does a global find-and-replace on the selected text using string.gsub

Details

Invokes the global replace dialog box, which lets you do powerful replacement on the selected text using Lua's string.gsub, allowing you to use regular expressions in the Find box, and optionally a custom replacement function.

Menu

Search -> Global Replace

Keyboard Shortcut

Ctrl+Shift+G

Example of script call

world.DoCommand "GlobalReplace"

See Also ...

Topic

 Notepad

Dialog

 Global Replace

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=GlobalReplace)


GoToBookmark

Summary

Goes to a bookmark

Menu

Display -> Go To Bookmark

Keyboard Shortcut

Ctrl+B

Example of script call

world.DoCommand "GoToBookmark"

(Help topic: command=GoToBookmark)


GoToLine

Summary

Go to a line number

Menu

Display -> Go To Line...

Keyboard Shortcut

Ctrl+Alt+L

Example of script call

world.DoCommand "GoToLine"

See Also ...

Dialog

 Go to line

(Help topic: command=GoToLine)


GoToMatchingBrace

Summary

Goes to matching brace character

Menu

Edit -> Go To Matching Brace

Keyboard Shortcut

Ctrl+E

Example of script call

world.DoCommand "GoToMatchingBrace"

(Help topic: command=GoToMatchingBrace)


GoToNotepadLine

Summary

Go To

Menu

Edit -> Go To...

Keyboard Shortcut

Ctrl+G

Example of script call

world.DoCommand "GoToNotepadLine"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=GoToNotepadLine)


GoToURL

Summary

Go To URL

Menu

Display -> Go To URL...

Keyboard Shortcut

Ctrl+Alt+J

Example of script call

world.DoCommand "GoToURL"

(Help topic: command=GoToURL)


Help

Summary

Display help for current task or command

Keyboard Shortcut

F1

Example of script call

world.DoCommand "Help"

(Help topic: command=Help)


HelpContents

Summary

List Help Contents

Menu

Help -> Contents

Example of script call

world.DoCommand "HelpContents"

(Help topic: command=HelpContents)


HelpIndex

Summary

List Help topics

Menu

Help -> Index

Example of script call

world.DoCommand "HelpIndex"

(Help topic: command=HelpIndex)


HighlightWord

Summary

Highlight a word or phrase

Menu

Display -> Highlight Word

Keyboard Shortcut

Ctrl+Alt+H

Example of script call

world.DoCommand "HighlightWord"

See Also ...

Dialog

 Highlight word

(Help topic: command=HighlightWord)


Immediate

Summary

Allows testing of scripts

Menu

Game -> Immediate...

Keyboard Shortcut

Ctrl+I

Example of script call

world.DoCommand "Immediate"

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Dialog

 Immediate

(Help topic: command=Immediate)


Import

Summary

Import items from XML file

Menu

File -> Import...

Keyboard Shortcut

Ctrl+Alt+I

Example of script call

world.DoCommand "Import"

See Also ...

Dialog

 Import

(Help topic: command=Import)


Info

Summary

Shows information about this world

Menu

Configure -> Info...

Keyboard Shortcut

Shift+Ctrl+I

Example of script call

world.DoCommand "Info"

See Also ...

Topic

 Information

Dialog

 Info

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: command=Info)


InfoBar

Summary

Show or hide the info bar

Menu

View -> Info Bar

Example of script call

world.DoCommand "InfoBar"

See Also ...

Topic

 Info bar - programmable information bar

Dialog

 Info bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: command=InfoBar)


InputGlobalChange

Summary

Does a "change all" in the current command

Menu

Input -> Global Change...

Keyboard Shortcut

Shift+Ctrl+G

Example of script call

world.DoCommand "InputGlobalChange"

See Also ...

Dialog

 Global change

(Help topic: command=InputGlobalChange)


InsertDateTime

Summary

Inserts the current date and time

Menu

Edit -> Insert Date/Time

Keyboard Shortcut

Ctrl+D

Example of script call

world.DoCommand "InsertDateTime"

(Help topic: command=InsertDateTime)


Introduction

Summary

Getting Started

Details

MUSHclient - a fast, easy-to-use MUD client for Windows

Written in C++ for high speed and compact size.

Has large scrollback buffer, command history, aliases, triggers, timers, keypad-navigation, speed-walking, and auto-say.

Supports scripting in VBscript, Jscript, PerlScript and Python, recognizes ANSI color codes, has user-defined macros, spell checking, proxy server support, chat system, built-in editor, and logging.

Also supports MUD extensions MCCP (Mud Client Compression Protocol) and MXP (Mud eXtension Protocol).

You can write your own plugins in any of the four supported scripting languages, or use ones written by others which are supplied with the program, or appear on our web site.

Getting started ...

Getting started with MUSHclient is easy!  Use the "quick connect" dialog to connect to a MUD.

Click on the links below for more information.

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Getting started

 Program features

 Speed walking

 Timers

 Triggers

Dialog

 Quick Connect

(Help topic: command=Introduction)


KeyName

Summary

Converts a keypress into its name

Details

This opens a dialog to convert a keypress into its name for use with the Accelerator function.

Menu

Input

Example of script call

world.DoCommand "KeyName"

See Also ...

Topics

 Scripting

 Utilities

Dialog

 Key name

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=KeyName)


Keypad0

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad0

Example of script call

world.DoCommand "Keypad0"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad0)


Keypad1

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad1

Example of script call

world.DoCommand "Keypad1"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad1)


Keypad2

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad2

Example of script call

world.DoCommand "Keypad2"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad2)


Keypad3

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad3

Example of script call

world.DoCommand "Keypad3"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad3)


Keypad4

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad4

Example of script call

world.DoCommand "Keypad4"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad4)


Keypad5

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad5

Example of script call

world.DoCommand "Keypad5"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad5)


Keypad6

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad6

Example of script call

world.DoCommand "Keypad6"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad6)


Keypad7

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad7

Example of script call

world.DoCommand "Keypad7"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad7)


Keypad8

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad8

Example of script call

world.DoCommand "Keypad8"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad8)


Keypad9

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Numpad9

Example of script call

world.DoCommand "Keypad9"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=Keypad9)


KeypadDash

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Subtract

Example of script call

world.DoCommand "KeypadDash"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=KeypadDash)


KeypadDot

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Decimal

Example of script call

world.DoCommand "KeypadDot"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=KeypadDot)


KeypadPlus

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Add

Example of script call

world.DoCommand "KeypadPlus"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=KeypadPlus)


KeypadSlash

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Divide

Example of script call

world.DoCommand "KeypadSlash"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=KeypadSlash)


KeypadStar

Summary

Executes a user-defined numeric keypad action.

Keyboard Shortcut

Multiply

Example of script call

world.DoCommand "KeypadStar"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Configure numeric keypad

(Help topic: command=KeypadStar)


KeysEscape

Summary

Escape key

Keyboard Shortcut

Esc

Example of script call

world.DoCommand "KeysEscape"

(Help topic: command=KeysEscape)


KeysTab

Summary

Tab key

Keyboard Shortcut

Tab

Example of script call

world.DoCommand "KeysTab"

(Help topic: command=KeysTab)


LineDown

Summary

Scrolls the display down a line

Menu

Display -> Line Down

Keyboard Shortcut

Ctrl+Down

Example of script call

world.DoCommand "LineDown"

(Help topic: command=LineDown)


LineUp

Summary

Scrolls the display upwards on line

Menu

Display -> Line Up

Keyboard Shortcut

Ctrl+Up

Example of script call

world.DoCommand "LineUp"

(Help topic: command=LineUp)


LogSession

Summary

Writes the game session out to a text file

Menu

File -> Log Session...

Keyboard Shortcut

Shift+Ctrl+J

Example of script call

world.DoCommand "LogSession"

See Also ...

Topic

 Logging

Dialog

 Log game session

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: command=LogSession)


Look

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+L

Example of script call

world.DoCommand "Look"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=Look)


LowerCase

Summary

Converts to all lower case

Menu

Convert -> Lower Case

Keyboard Shortcut

Shift+Ctrl+L

Example of script call

world.DoCommand "LowerCase"

(Help topic: command=LowerCase)


MacroCtrlF10

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F10

Example of script call

world.DoCommand "MacroCtrlF10"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF10)


MacroCtrlF11

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F11

Example of script call

world.DoCommand "MacroCtrlF11"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF11)


MacroCtrlF12

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F12

Example of script call

world.DoCommand "MacroCtrlF12"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF12)


MacroCtrlF2

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F2

Example of script call

world.DoCommand "MacroCtrlF2"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF2)


MacroCtrlF3

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F3

Example of script call

world.DoCommand "MacroCtrlF3"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF3)


MacroCtrlF5

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F5

Example of script call

world.DoCommand "MacroCtrlF5"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF5)


MacroCtrlF7

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F7

Example of script call

world.DoCommand "MacroCtrlF7"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF7)


MacroCtrlF8

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F8

Example of script call

world.DoCommand "MacroCtrlF8"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF8)


MacroCtrlF9

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+F9

Example of script call

world.DoCommand "MacroCtrlF9"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroCtrlF9)


MacroF10

Summary

Executes a user-defined macro.

Keyboard Shortcut

F10

Example of script call

world.DoCommand "MacroF10"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF10)


MacroF11

Summary

Executes a user-defined macro.

Keyboard Shortcut

F11

Example of script call

world.DoCommand "MacroF11"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF11)


MacroF12

Summary

Executes a user-defined macro.

Keyboard Shortcut

F12

Example of script call

world.DoCommand "MacroF12"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF12)


MacroF2

Summary

Executes a user-defined macro.

Keyboard Shortcut

F2

Example of script call

world.DoCommand "MacroF2"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF2)


MacroF3

Summary

Executes a user-defined macro.

Keyboard Shortcut

F3

Example of script call

world.DoCommand "MacroF3"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF3)


MacroF4

Summary

Executes a user-defined macro.

Keyboard Shortcut

F4

Example of script call

world.DoCommand "MacroF4"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF4)


MacroF5

Summary

Executes a user-defined macro.

Keyboard Shortcut

F5

Example of script call

world.DoCommand "MacroF5"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF5)


MacroF7

Summary

Executes a user-defined macro.

Keyboard Shortcut

F7

Example of script call

world.DoCommand "MacroF7"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF7)


MacroF8

Summary

Executes a user-defined macro.

Keyboard Shortcut

F8

Example of script call

world.DoCommand "MacroF8"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF8)


MacroF9

Summary

Executes a user-defined macro.

Keyboard Shortcut

F9

Example of script call

world.DoCommand "MacroF9"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroF9)


MacroShiftF10

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F10

Example of script call

world.DoCommand "MacroShiftF10"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF10)


MacroShiftF11

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F11

Example of script call

world.DoCommand "MacroShiftF11"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF11)


MacroShiftF12

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F12

Example of script call

world.DoCommand "MacroShiftF12"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF12)


MacroShiftF2

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F2

Example of script call

world.DoCommand "MacroShiftF2"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF2)


MacroShiftF3

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F3

Example of script call

world.DoCommand "MacroShiftF3"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF3)


MacroShiftF4

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F4

Example of script call

world.DoCommand "MacroShiftF4"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF4)


MacroShiftF5

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F5

Example of script call

world.DoCommand "MacroShiftF5"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF5)


MacroShiftF6

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F6

Example of script call

world.DoCommand "MacroShiftF6"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF6)


MacroShiftF7

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F7

Example of script call

world.DoCommand "MacroShiftF7"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF7)


MacroShiftF8

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F8

Example of script call

world.DoCommand "MacroShiftF8"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF8)


MacroShiftF9

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+F9

Example of script call

world.DoCommand "MacroShiftF9"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=MacroShiftF9)


MacToDos

Summary

Converts selection from Mac text to DOS text

Menu

Convert -> Mac To DOS

Example of script call

world.DoCommand "MacToDos"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=MacToDos)


MakeMultiLineTrigger

Summary

Make a multi-line trigger

Menu

Display -> MultiLine Trigger

Example of script call

world.DoCommand "MakeMultiLineTrigger"

See Also ...

Dialog

 Make Multi-Line Trigger

(Help topic: command=MakeMultiLineTrigger)


Mapper

Summary

Shows the mapping dialog

Menu

Game -> Mapper

Keyboard Shortcut

Ctrl+Alt+M

Example of script call

world.DoCommand "Mapper"

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Dialog

 Mapper

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: command=Mapper)


Maximize

Summary

Maximizes the world window

Details

Causes the world window to be displayed in the maximized state.

Example of script call

world.DoCommand "Maximize"

(Help topic: command=Maximize)


MinimiseProgram

Summary

Minimizes MUSHclient

Menu

Game -> Minimize Program

Keyboard Shortcut

Ctrl+M

Example of script call

world.DoCommand "MinimiseProgram"

(Help topic: command=MinimiseProgram)


Minimize

Summary

Minimize the current window

Menu

Window -> Minimize

Keyboard Shortcut

Shift+Ctrl+M

Example of script call

world.DoCommand "Minimize"

(Help topic: command=Minimize)


MudLists

Summary

Web page of MUD lists

Menu

Help -> MUD Lists...

Example of script call

world.DoCommand "MudLists"

(Help topic: command=MudLists)


New

Summary

Connect to a new world

Menu

File -> New World...

Example of script call

world.DoCommand "New"

(Help topic: command=New)


NewWindow

Summary

Open another window for the active document

Menu

Window -> New Window

Example of script call

world.DoCommand "NewWindow"

(Help topic: command=NewWindow)


NextCommand

Summary

Next Command

Menu

Input -> Next Command

Example of script call

world.DoCommand "NextCommand"

(Help topic: command=NextCommand)


NextPane

Summary

Switch to the next window pane

Keyboard Shortcut

F6

Example of script call

world.DoCommand "NextPane"

(Help topic: command=NextPane)


NoCommandEcho

Summary

No Command Echo

Menu

Display -> No Command Echo

Keyboard Shortcut

Ctrl+Alt+E

Example of script call

world.DoCommand "NoCommandEcho"

(Help topic: command=NoCommandEcho)


North

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+Ctrl+N

Example of script call

world.DoCommand "North"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=North)


NotesWorkArea

Summary

Opens a notepad window for working on long commands etc.

Menu

Edit -> Notepad

Keyboard Shortcut

Ctrl+Alt+W

Example of script call

world.DoCommand "NotesWorkArea"

See Also ...

Topic

 Notepad

Dialog

 Choose notepad window

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: command=NotesWorkArea)


Open

Summary

Open an existing world

Menu

File -> Open World...

Example of script call

world.DoCommand "Open"

(Help topic: command=Open)


OpenWorldsInStartupList

Summary

Opens all worlds listed in Global Preferences

Menu

File -> Open Worlds In Startup List

Example of script call

world.DoCommand "OpenWorldsInStartupList"

(Help topic: command=OpenWorldsInStartupList)


PageDown

Summary

Goes down a page

Menu

Display -> Page Down

Keyboard Shortcut

Ctrl+PageDown

Example of script call

world.DoCommand "PageDown"

(Help topic: command=PageDown)


Pageup

Summary

Goes up a page

Menu

Display -> Page Up

Keyboard Shortcut

Ctrl+PageUp

Example of script call

world.DoCommand "Pageup"

(Help topic: command=Pageup)


Paste

Summary

Insert Clipboard contents

Menu

Edit -> Paste

Keyboard Shortcut

Shift+Insert

Example of script call

world.DoCommand "Paste"

(Help topic: command=Paste)


PasteFile

Summary

Pastes the contents of a text file into the world

Menu

Input -> Send File...

Keyboard Shortcut

Shift+Ctrl+O

Example of script call

world.DoCommand "PasteFile"

(Help topic: command=PasteFile)


PasteToMush

Summary

Sends the contents of the clipboard directly to the current world

Menu

Edit -> Paste To World...

Keyboard Shortcut

Shift+Ctrl+V

Example of script call

world.DoCommand "PasteToMush"

(Help topic: command=PasteToMush)


Plugins

Summary

Shows plugins active for this world

Menu

File -> Plugins...

Keyboard Shortcut

Shift+Ctrl+P

Example of script call

world.DoCommand "Plugins"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugins

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: command=Plugins)


PluginWizard

Summary

Invokes the plugin creation wizard

Details

Use this to create plugins using the Plugin Wizard.

Menu

File -> Plugin Wizard...

Keyboard Shortcut

Shift+Ctrl+Alt+P

Example of script call

world.DoCommand "PluginWizard"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Dialog

 Plugin wizard - Name and Purpose

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: command=PluginWizard)


Preferences

Summary

Set world details (name, font, colour etc.)

Details

Invokes the world configuration dialog boxes.

Menu

Configure -> All Configuration...

Keyboard Shortcut

Alt+Enter

Example of script call

world.DoCommand "Preferences"

See Also ...

Dialog

 World name and TCP/IP address

(Help topic: command=Preferences)


PreviousCommand

Summary

Previous Command

Menu

Input -> Previous Command

Example of script call

world.DoCommand "PreviousCommand"

(Help topic: command=PreviousCommand)


Print

Summary

Prints the current world output

Menu

File -> Print...

Example of script call

world.DoCommand "Print"

(Help topic: command=Print)


PrintNotepad

Summary

Prints the current world

Menu

File -> Print...

Keyboard Shortcut

Ctrl+P

Example of script call

world.DoCommand "PrintNotepad"

(Help topic: command=PrintNotepad)


PrintPreview

Summary

Print Preview

Menu

File -> Print Preview

Example of script call

world.DoCommand "PrintPreview"

(Help topic: command=PrintPreview)


PrintSetup

Summary

Change the printer and printing options

Menu

File -> Print Setup...

Example of script call

world.DoCommand "PrintSetup"

(Help topic: command=PrintSetup)


QuickConnect

Summary

Quickly establishes a connection to a new world

Details

Use this to quickly connect to a MUD by simply filling in the MUD name, IP address and port.

Menu

Connection -> Quick Connect...

Keyboard Shortcut

Shift+Ctrl+Alt+K

Example of script call

world.DoCommand "QuickConnect"

See Also ...

Dialog

 Quick Connect

(Help topic: command=QuickConnect)


QuoteForumCodes

Summary

Escapes the characters [, ], \ with a backslash.

Menu

Convert -> Quote Forum Codes

Keyboard Shortcut

Shift+Ctrl+Q

Example of script call

world.DoCommand "QuoteForumCodes"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=QuoteForumCodes)


QuoteLines

Summary

Adds '> ' to the start of each line

Menu

Convert -> Quote Lines

Keyboard Shortcut

Ctrl+Q

Example of script call

world.DoCommand "QuoteLines"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=QuoteLines)


RecallText

Summary

Recalls all lines matching a string into a separate window

Details

If text is currently selected in the output window, lines matching the selected text are recalled without the dialog box being displayed.

Thus, a quick way to recall events relating to (another player, say) is to double-click on the player/mob name of interest, and the hit Ctrl+U.

Menu

Display -> Recall Text...

Keyboard Shortcut

Ctrl+U

Example of script call

world.DoCommand "RecallText"

See Also ...

Dialog

 Recall

(Help topic: command=RecallText)


ReconnectOnDisconnect

Summary

Automatically reconnect to a world if connection lost

Menu

Connection -> Reconnect On Disconnect

Example of script call

world.DoCommand "ReconnectOnDisconnect"

(Help topic: command=ReconnectOnDisconnect)


RefreshRecalledData

Summary

Refreshes window by doing another "recall"

Menu

Edit -> Refresh Recalled Data

Keyboard Shortcut

F5

Example of script call

world.DoCommand "RefreshRecalledData"

(Help topic: command=RefreshRecalledData)


ReloadDefaults

Summary

Reload global default colours, triggers etc.

Menu

File -> Reload Defaults

Keyboard Shortcut

Ctrl+Alt+R

Example of script call

world.DoCommand "ReloadDefaults"

(Help topic: command=ReloadDefaults)


ReloadNamesFile

Summary

Reloads the file used for name generation

Menu

Edit -> Reload Names File...

Example of script call

world.DoCommand "ReloadNamesFile"

(Help topic: command=ReloadNamesFile)


ReloadScriptFile

Summary

Forces script source file to be reprocessed

Details

This causes the script file associated with this world to be recompiled.

You should do this after correcting any syntax errors which have been reported in your script.

Reloading the script file also re-initializes the script engine, thus clearing any variables which were established during a previous script execution.

In the case of Lua scripts it also causes the Lua 'sandbox' to be re-executed.

Menu

Game -> Reload Script File

Keyboard Shortcut

Shift+Ctrl+R

Example of script call

world.DoCommand "ReloadScriptFile"

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

(Help topic: command=ReloadScriptFile)


RemoveBlanks

Summary

Removes multiple whitespace (spaces, tabs) from selection

Menu

Convert -> Remove Extra Blanks

Keyboard Shortcut

Ctrl+B

Example of script call

world.DoCommand "RemoveBlanks"

(Help topic: command=RemoveBlanks)


RepeatLastCommand

Summary

Repeat Last Command

Menu

Input -> Repeat Last Command

Keyboard Shortcut

Ctrl+R

Example of script call

world.DoCommand "RepeatLastCommand"

(Help topic: command=RepeatLastCommand)


RepeatLastWord

Summary

Inserts the last word from the previous line

Menu

Edit -> Recall Last Word

Keyboard Shortcut

Ctrl+Backspace

Example of script call

world.DoCommand "RepeatLastWord"

(Help topic: command=RepeatLastWord)


ReplaceNotepad

Summary

Replace

Menu

Search -> Replace

Keyboard Shortcut

Ctrl+H

Example of script call

world.DoCommand "ReplaceNotepad"

(Help topic: command=ReplaceNotepad)


ResetAllTimers

Summary

Resets all timers

Menu

Game -> Reset All Timers

Keyboard Shortcut

Shift+Ctrl+T

Example of script call

world.DoCommand "ResetAllTimers"

(Help topic: command=ResetAllTimers)


ResetToolbars

Summary

Reset Toolbar Locations

Menu

View -> Reset Toolbar Locations

Example of script call

world.DoCommand "ResetToolbars"

(Help topic: command=ResetToolbars)


Restore

Summary

Restores the world window

Details

Causes the world window to be displayed in the normal (restored) state.

Example of script call

world.DoCommand "Restore"

(Help topic: command=Restore)


Save

Summary

Save the active world details

Menu

File -> Save World Details

Keyboard Shortcut

Ctrl+S

Example of script call

world.DoCommand "Save"

(Help topic: command=Save)


SaveAs

Summary

Save world details with a new name

Menu

File -> Save World Details As...

Example of script call

world.DoCommand "SaveAs"

(Help topic: command=SaveAs)


SaveSelection

Summary

Saves the selected output as a text file

Menu

File -> Save Selection...

Example of script call

world.DoCommand "SaveSelection"

(Help topic: command=SaveSelection)


SelectAll

Summary

Select all text

Menu

Edit -> Select All

Keyboard Shortcut

Ctrl+A

Example of script call

world.DoCommand "SelectAll"

(Help topic: command=SelectAll)


SelectMatchingBrace

Summary

Selects range from brace to matching brace

Menu

Edit -> Select To Matching Brace

Keyboard Shortcut

Shift+Ctrl+E

Example of script call

world.DoCommand "SelectMatchingBrace"

(Help topic: command=SelectMatchingBrace)


SendMailTo

Summary

Send Mail To

Menu

Display -> Send Mail To...

Example of script call

world.DoCommand "SendMailTo"

(Help topic: command=SendMailTo)


SendToAllWorlds

Summary

Sends a message to all worlds

Menu

Game -> Send To All Worlds...

Keyboard Shortcut

Ctrl+Alt+S

Example of script call

world.DoCommand "SendToAllWorlds"

See Also ...

Dialog

 Send to multiple worlds

(Help topic: command=SendToAllWorlds)


SendToCommandWindow

Summary

Sends the selection to the command window of the related world

Menu

Edit -> Send To Command Window

Keyboard Shortcut

Shift+Ctrl+C

Example of script call

world.DoCommand "SendToCommandWindow"

(Help topic: command=SendToCommandWindow)


SendToScript

Summary

Sends the selection to the script engine of the related world

Details

This sends the entire window (or selected text) to the script engine, if any, of the related world.

Menu

Edit -> Send To Immediate

Keyboard Shortcut

Shift+Ctrl+I

Example of script call

world.DoCommand "SendToScript"

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

(Help topic: command=SendToScript)


SendToWorld

Summary

Sends the window (or selection) to the related world

Menu

Edit -> Send To World

Keyboard Shortcut

Shift+Ctrl+S

Example of script call

world.DoCommand "SendToWorld"

(Help topic: command=SendToWorld)


South

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+Ctrl+S

Example of script call

world.DoCommand "South"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=South)


SpellCheck

Summary

Spell checks the command in the command window

Menu

Edit -> Spell Check

Keyboard Shortcut

Ctrl+J

Example of script call

world.DoCommand "SpellCheck"

See Also ...

Topic

 Spell checker

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: command=SpellCheck)


Start

Summary

Goes to start of view

Menu

Display -> Start

Keyboard Shortcut

Ctrl+Home

Example of script call

world.DoCommand "Start"

(Help topic: command=Start)


StopSoundPlaying

Summary

Stops the current MIDI file playing

Menu

Display -> Stop Sound Playing

Keyboard Shortcut

Ctrl+Alt+B

Example of script call

world.DoCommand "StopSoundPlaying"

(Help topic: command=StopSoundPlaying)


Take

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+T

Example of script call

world.DoCommand "Take"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=Take)


TestTrigger

Summary

Test trigger evaluation

Menu

Game -> Test Trigger...

Example of script call

world.DoCommand "TestTrigger"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: command=TestTrigger)


TextAttributes

Summary

Gets the attributes of the first character of the selection

Menu

Display -> Text Attributes...

Keyboard Shortcut

Ctrl+Alt+A

Example of script call

world.DoCommand "TextAttributes"

See Also ...

Topic

 Information

Dialog

 Text attributes

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: command=TextAttributes)


TileWindows

Summary

Arrange windows horizontally as non-overlapping tiles

Details

Tiles all open windows as horizontal tiles (rows).

Menu

Window -> Tile

Example of script call

world.DoCommand "TileWindows"

(Help topic: command=TileWindows)


TileWindowsVertically

Summary

Arrange windows vertically as non-overlapping tiles

Details

Tiles all opened windows as vertical tiles (columns).

Menu

Window -> Tile Vertically

Example of script call

world.DoCommand "TileWindowsVertically"

(Help topic: command=TileWindowsVertically)


TipOfTheDay

Summary

Shows the Tip of the Day

Menu

Help -> Tip Of The Day...

Example of script call

world.DoCommand "TipOfTheDay"

See Also ...

Dialog

 Tip of the Day

(Help topic: command=TipOfTheDay)


Trace

Summary

Trace triggers/aliases/timers/scripts

Menu

Game -> Trace

Keyboard Shortcut

Ctrl+Alt+T

Example of script call

world.DoCommand "Trace"

(Help topic: command=Trace)


UnconvertHTMLspecial

Summary

Converts HTML specials back to normal, eg. &lt; to <

Menu

Convert -> Unconvert HTML special

Keyboard Shortcut

Shift+Ctrl+Alt+H

Example of script call

world.DoCommand "UnconvertHTMLspecial"

(Help topic: command=UnconvertHTMLspecial)


Undo

Summary

Undo the last action

Menu

Edit -> Undo

Keyboard Shortcut

Alt+Backspace

Example of script call

world.DoCommand "Undo"

(Help topic: command=Undo)


UnixToDos

Summary

Converts selection from Unix text to DOS text

Menu

Convert -> Unix To DOS

Example of script call

world.DoCommand "UnixToDos"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=UnixToDos)


Up

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+Ctrl+U

Example of script call

world.DoCommand "Up"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=Up)


UpperCase

Summary

Converts to all upper case

Menu

Convert -> Upper Case

Keyboard Shortcut

Shift+Ctrl+U

Example of script call

world.DoCommand "UpperCase"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: command=UpperCase)


UsingHelp

Summary

Display instructions about how to use help

Menu

Help -> Using Help

Example of script call

world.DoCommand "UsingHelp"

(Help topic: command=UsingHelp)


ViewStatusbar

Summary

Show or hide the status bar

Menu

View -> Status Bar

Example of script call

world.DoCommand "ViewStatusbar"

(Help topic: command=ViewStatusbar)


ViewToolbar

Summary

Show or hide the toolbar

Menu

View -> Toolbar

Example of script call

world.DoCommand "ViewToolbar"

(Help topic: command=ViewToolbar)


ViewWorldToolbar

Summary

Show or hide the world toolbar

Menu

View -> World Toolbar

Example of script call

world.DoCommand "ViewWorldToolbar"

(Help topic: command=ViewWorldToolbar)


WebPage

Summary

Goes to the MUSHclient web page on the Internet

Menu

Help -> MUSHclient Web Page...

Keyboard Shortcut

Shift+Ctrl+Alt+W

Example of script call

world.DoCommand "WebPage"

(Help topic: command=WebPage)


West

Summary

Executes a user-defined macro.

Keyboard Shortcut

Shift+Ctrl+W

Example of script call

world.DoCommand "West"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=West)


Whisper

Summary

Executes a user-defined macro.

Keyboard Shortcut

Ctrl+W

Example of script call

world.DoCommand "Whisper"

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Dialog

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: command=Whisper)


WindowsSocketInformation

Summary

Information about the version of Winsock in use

Menu

File -> Windows Socket Info...

Example of script call

world.DoCommand "WindowsSocketInformation"

See Also ...

Topic

 Information

Dialog

 Windows Sockets information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: command=WindowsSocketInformation)


WordCount

Summary

Counts words, lines and characters in document

Menu

Edit -> Word Count...

Keyboard Shortcut

Alt+Enter

Example of script call

world.DoCommand "WordCount"

(Help topic: command=WordCount)


World1

Summary

Activates world #1

Details

Click this button to activate world 1 in the world activity sequence.

Keyboard Shortcut

Ctrl+1

Example of script call

world.DoCommand "World1"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World1)


World10

Summary

Activates world #10

Details

Click this button to activate world 10 in the world activity sequence.

Keyboard Shortcut

Ctrl+0

Example of script call

world.DoCommand "World10"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World10)


World2

Summary

Activates world #2

Details

Click this button to activate world 2 in the world activity sequence.

Keyboard Shortcut

Ctrl+2

Example of script call

world.DoCommand "World2"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World2)


World3

Summary

Activates world #3

Details

Click this button to activate world 3 in the world activity sequence.

Keyboard Shortcut

Ctrl+3

Example of script call

world.DoCommand "World3"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World3)


World4

Summary

Activates world #4

Details

Click this button to activate world 4 in the world activity sequence.

Keyboard Shortcut

Ctrl+4

Example of script call

world.DoCommand "World4"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World4)


World5

Summary

Activates world #5

Details

Click this button to activate world 5 in the world activity sequence.

Keyboard Shortcut

Ctrl+5

Example of script call

world.DoCommand "World5"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World5)


World6

Summary

Activates world #6

Details

Click this button to activate world 6 in the world activity sequence.

Keyboard Shortcut

Ctrl+6

Example of script call

world.DoCommand "World6"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World6)


World7

Summary

Activates world #7

Details

Click this button to activate world 7 in the world activity sequence.

Keyboard Shortcut

Ctrl+7

Example of script call

world.DoCommand "World7"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World7)


World8

Summary

Activates world #8

Details

Click this button to activate world 8 in the world activity sequence.

Keyboard Shortcut

Ctrl+8

Example of script call

world.DoCommand "World8"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World8)


World9

Summary

Activates world #9

Details

Click this button to activate world 9 in the world activity sequence.

Keyboard Shortcut

Ctrl+9

Example of script call

world.DoCommand "World9"

See Also ...

Topics

 Activity window

 Getting started

(Help topic: command=World9)


WrapLines

Summary

Removes line endings (wraps paragraphs)

Menu

Convert -> Wrap Lines

Keyboard Shortcut

Ctrl+L

Example of script call

world.DoCommand "WrapLines"

(Help topic: command=WrapLines)


WrapOutput

Summary

Wrap output lines at edge

Menu

Game -> Wrap Output

Example of script call

world.DoCommand "WrapOutput"

(Help topic: command=WrapOutput)


Activity window

If you are playing in multiple worlds (MUDs) you can monitor their activity in a couple of ways.

Activity Toolbar

Click on the View menu -> Activity Toolbar to show the activity "buttons" if they are not already visible. You can drag them around, either docking them to the top, bottom or sides of the window, or leave them free as a floating window.

The buttons represent the first 10 worlds open, and change colour depending if the world is open, closed, or has new activity. You can click on any of the buttons to activate its related world window.

Activity List

This is a larger window that will show all open worlds (even if there are more than 10). It can be resized, moved, and the column order changed, to customise it to your requirements.

See Also ...

Topic

 Getting started

Commands

 World1 (Activates world #1)

 World10 (Activates world #10)

 World2 (Activates world #2)

 World3 (Activates world #3)

 World4 (Activates world #4)

 World5 (Activates world #5)

 World6 (Activates world #6)

 World7 (Activates world #7)

 World8 (Activates world #8)

 World9 (Activates world #9)

Dialog

 Activity window

(Help topic: general=activity)


Aliases

Aliases let you respond to something you have typed.

For example, an alias "GF" might expand to "open bag; get food"

You can also make aliases invoke scripts, make notes on the screen, do speedwalks, and many other things.

To respond to some text arriving from the MUD, use a trigger instead.

You can use wildcards to put "variable" information into the alias. For example, say you want to make an alias that gets something from your bag, and quaffs it, but the "something" might change from time to time, use an asterisk to represent the unknown thing. For example:

Match: gq *

Send:

get %1 bag

quaff %1

Then you might type:

gq potion

You can have up to 999 wildcards (which become %1 to %9) with %0 representing "the whole matching text". See below for how to access the higher numbered wildcards.

Another example, which uses two wildcards, might be used if you had to prepare a spell before using it.

Match: c * *

Send:

prepare %1

cast %1 %2

Then you might type:

c heal gandalf

Alias scripts

Aliases can execute script commands by simply putting the command into the "send" box and selecting "send to script".

However for more complex scripts you can put scripts into your script file (see scripting configuration tab for the world) and then call the script from the alias. To do this put the name of the script subroutine into the alias's script box.

The script subroutine must* have three arguments, as follows:

•	Name of the alias

•	The matching line

•	An array of the first 10 wildcards

* If you are using Lua, then the arguments are optional, as usual.

An example script in the VBscript language would be:

sub MyAlias (name, line, wildcards)

  Note "Alias " & name & " matched."

  Note "Wildcard 1 was" & wildcards (1)

end sub

Wildcard 10 is the entire matching sequence, which is not necessarily the same as the matching line in the case of regular expressions.

Other wildcards can be accessed by using the GetAliasWildcard script routine (for example, named wildcards, or wildcards over number 9).

Wildcards

A powerful feature in matching triggers or aliases is the ability to specify "wildcards" which are variable information that might change from time to time.

For example:

k *

In this case the asterisk represents the name of the unknown target you wish to kill.

Using the wildcard in the "send" box ...

To use this unknown quantity you can refer to it as %1 (for the first wildcard) in the "send" box, like this:

kick %1

The second wildcard is %2, and so on. Wildcard %0 is a special case which represents the entire matching text.

For wildcards above 9 you can use this syntax:

kick %<22>

The number in the angled brackets can be from 0 to 999.

Also, if you use regular expressions, you can name wildcards, like this:

^k (?P<target>.*)$

This names the wildcard as "target". You can then use this name in a similar way:

kick %<target>

See Also ...

Topics

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Command

 ConfigureAliases (Define aliases)

Dialogs

 Alias configuration (list)

 Edit alias

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: general=aliases)


Arrays

MUSHclient offers internal "key/value pairs" which it calls arrays.

You can have any number of arrays for each world, and also for each plugin.

Each array has an alphanumeric name (eg. "spells").

Inside each array is any number of key/value pairs (eg. mana = 22).

Script routines let you add, delete, import, and export from arrays into string variables. You can also enumerate (get a list of) all known arrays, or all keys in a particular array.

These functions are available from version 3.46 onwards.

Array and key names

Each array (eg. "spells") and each array item key (eg. "cold") has a name. The name is case-sensitive, and is stored exactly "as is" (no spaces are removed, for example). You can use any (8-bit) character for array and key names except for the "nul" character (hex 00).

Array and key names are unique, so if you have an array, and put something into key "a", and then something else into key "a", the original contents will be replaced.

Numeric array and key names

In order to allow arrays to be used as straight numeric sequences, numeric keys are treated specially. If an array or key name consists entirely of numbers, with an optional leading + or - sign, then the name is converted to a number and sorted into numeric order, rather than alpanumeric order. Numeric keys are sorted before all other keys.

Thus, the keys "1", "0001", "+1" are all considered the same.

See Also ...

Topics

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: general=Arrays)


Auto-mapper

Introduction

The intention of the mapper is that you can use it to generate a speed walk string (for use in an alias), by "teaching" it the way to go, rather than having to record each move you make on a bit of paper. For example, you might start at the city square, and walk around until you find a grocery shop, and then record the steps needed to find it, so you can find it again next time more easily. Also, by generating the reverse steps, you could move back from the grocery shop to the city square very easily.

This is not a GUI mapper (in other words, it doesn't attempt to draw maps on the screen), but is a system for recording the steps you have taken, with a view to re-using them later.

For a GUI mapper see this forum posting:

http://mushclient.com/forum/?id=10138

Once activated, it will do the following:

Automatically record "standard" compass directions

 These are defined as:

  n (north), s (south), e (east), w (west), ne, se, nw, sw, u (up) and d (down)

  The directions in brackets are synonyms - either may be used.

Record other commands

On request, record any other commands which move you around, eg. "teleport", "go portal", "open door", "unlock gate". You can use Mapper special command to do this.

Record comments

To help work out where the mapping sequence is you can add comments manually (eg. "Outside Darkhaven"). Also, on an MXP-enabled MUD MUSHclient will automatically add room names to the auto-map sequence.

Detect movement failure

Automatically detect when a direction command fails to move you, and remove the failed direction from the mapping list. This is done by matching on a user-supplied "failure" string, eg. "Alas, you cannot go that way", "You cannot go north", "The gate is locked", "The door is closed". The failure string can be a "regular expression", thus combinations of the above may be expressed, eg.

^(You cannot go that way|The gate is locked)$

Remove backtracking

Automatically (if desired) remove backtracking. For example, if you go North, and then South, you would normally end up back where you started. The auto-mapper will remove such instances, so that the end "direction string" does not contain false starts.

Produce a speedwalk string

Convert the recorded directions into a "speedwalk string".

Produce a reverse speedwalk

Also provide a "reverse speedwalk", so you can go back the way you came.

Make a forwards and backwards alias

On request, turn the direction string into an alias. Ditto for the reverse direction.

Review your progress

You can review the recorded steps at any point, and either keep adding to them, or start a new pathway.

Correct mistakes

If you accidentally record a direction that wasn't taken, it can be removed from the mapping sequence.

Take the reverse route

You can take the reverse route by clicking a single button.

See Also ...

Topics

 Aliases

 Speed walking

Commands

 DoMapperComment (Sends comment to auto-mapper)

 DoMapperSpecial (Do a non-standard direction command)

 Mapper (Shows the mapping dialog)

Dialogs

 Map Comment

 Mapper

 Special Map Movement

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: general=mapper)


Chat system

The chat features lets you do peer-to-peer chatting. That is, talk to other players without going through the MUD server. This could be useful for:

•	privacy (your conversation cannot be listened to or logged by the MUD)

•	if the MUD is down you can still chat

•	talking when you normally can't (eg. in a silent room, if stunned, etc.)

•	automating interaction between people in a group (eg. PK groups)

The chat features has detailed support in the MUSHclient scripting language.

See Also ...

Topic

 Getting started

Commands

 ChatSessions (Show all chat sessions for this world)

 ConfigureChat (Configure chat settings)

Dialogs

 Call chat user

 Chat

 Chat details

 Chat sessions

 Chat to all

 Emote to all

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: general=chat)


Colour management

Colour Palette

To understand how the program handles colours, it is necessary to discuss the concept of a colour "palette". MUSHclient recognises 8 ANSI "normal" colours (black, red, green, yellow, blue, magenta, cyan and white), and the same 8 colours in "bold". The codes to change colours may be sent by a particular MUD if the appropriate function calls are made by a room designer. The normal colour is white text on a black background.

However, the actual colours that are displayed depend on the colour palette for a particular world. For example "black" might actually display as grey, and "white" might actually display as green.

Changing colours

To change colours, use the "ANSI Colour" configuration dialog. You can right-mouse-click to copy colours from one colour swatch to another. Click on the colour swatches to change the colour.

Custom colours

Triggers and scripts can also use custom colours, which are a further 16 colours (pairs of foreground/background colours) which are configurable in the "Custom Colour" configuration dialog.

RGB colours

Triggers and scripts can also use the full RGB colour gamut - which is 256 (red) X 256 (green) X 256 (blue) colour combinations (a total of 16,777,216 possible colours). This allows for a wide range of colour presentation. In a trigger select the "other..." item from the colour combo-box. In scripts you can use things like world.ColourNote to send messages to the window in any colour.

Saving colours

Colours from one world can be saved to a "colour file" and then loaded into another world, thus keeping them all to the same colour scheme.

Mapping colours

From version 3.54 onwards you can also "map" one colour to another. This is provided to allow you to customise MXP colours which do not otherwise have a mechanism for being displayed differently. See the MapColour function for more details. This allows you to have a "last moment" mapping of a colour (that you don't like) to a different colour (that you prefer).

See Also ...

Topic

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: general=colours)


Commented softcode

This lets you send large amounts of data to the world in a single operation (eg. from a disk file). You might use this for sending attibutes to a MUSH or similar.

Commented Softcode

The purpose of this is to keep the (rather obscure) softcode commands in a text file with lots of comments in them. Then, in sending them to the MUSH the comments are stripped out.

Basically, there are two different kinds of softcode formatting - #-commented and @@-commented, with slightly different rules.  The basic part is you take a segment like

&attrib Object=

Bleh

Bleh

Bleh

-

You start with the first line and append all subsequent lines until you get a '-' in the first column.  The different commenting styles are like this:

# This is #-commenting

# Comments are determined by having a '#' in the first column.

&attrib Object=

Bleh

Bleh  # This goes through as well - # not on first column

Bleh @@ In this case, @@ comments go through

-

The other commenting style

@@ This is @@-commenting

@@ Basically, anything after @@ on a line is stripped

MUSHclient determines which style to use by the first non-blank line of softcode.

If the first line starts with "#" then hash-commenting is used, otherwise the "@@" commenting style is used.

See Also ...

Topic

 Sending to the world

Command

 ConfigureSendFile (Sets 'send file' options)

Dialogs

 Paste

 Send

(Help topic: general=send_paste)


Database (SQLite)

MUSHclient from version 4.40 onwards has support for accessing SQLite 3 databases.

•	Databases are created and manipulated purely by script commands, generally intended to be inside plugins.

•	You can have any number of databases open at once. Each one has a name which is used by the script to refer to it.

•	Databases can be purely "in memory" by using the filename ":memory:".

General technique

•	Open the database with DatabaseOpen

•	Execute "action" SQL statements with DatabaseExec

•	To query data from the database:

•	Prepare an SQL statement with DatabasePrepare

•	Get column names with DatabaseColumnName or DatabaseColumnNames

•	Step through each row with DatabaseStep

•	Get column values with DatabaseColumnValue or DatabaseColumnValues

•	After all rows are extracted, finalize the statement with DatabaseFinalize

•	Close the database with DatabaseClose

For more information, see:

http://www.gammon.com.au/db

You can also use the Lua sqlite3 interface to work on SQLite databases, in Lua only.

Example of creating a database

db = "mainDatabase"  -- internal identifier

DatabaseOpen (db, GetInfo (66) .. "mytestdb.sqlite", 6)

DatabaseExec (db, [[

DROP TABLE IF EXISTS weapons;

CREATE TABLE weapons(

        weapon_id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,

        name      TEXT NOT NULL,

        damage    INT DEFAULT 10,

        weight    REAL

      );

      ]])

DatabaseClose (db)  -- close it

It is better to check the result from calling functions like DatabaseExec, otherwise they may silently fail (eg, with an SQL syntax error) like this:

status = DatabaseExec (db, [[

DROP TABLE IF EXISTS weapons;

CREATE TABLE weapons(

        weapon_id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,

        name      TEXT NOT NULL,

        damage    INT DEFAULT 10,

        weight    REAL

      );

      ]])

if status ~= sqlite3.OK then

  print ("Error creating weapons table: ", DatabaseError(db))

end -- if not OK

The documentation for DatabaseExec suggests a function (dbcheck) which can be used as a generic return-code checker.

Example of adding a row of data

DatabaseExec (db, "INSERT INTO weapons (name, damage) VALUES ('Nick''s sword', 42)")

Note that if you need to use quotes inside a string, the quotes must be doubled, as shown above.

Example of selecting some rows and displaying them

As described above, you need to "prepare" the SQL statement first. Once prepared you can find how many columns are in it, and the column names.

Then you "step" through the rows, one by one, getting the column values. These can then be printed, saved, or acted up.

Finally you "finalize" the SQL statement, releasing it so you can do another operation.

-- prepare a query

DatabasePrepare (db, "SELECT * FROM weapons ORDER BY name")

-- find the column names

names = DatabaseColumnNames (db)

-- find how many columns there are

cols = DatabaseColumns (db)

-- step to get the first row

rc = DatabaseStep (db)  -- read first row

-- now loop, displaying each row, and getting the next one

while rc == sqlite3.ROW do

  print ("")

  values = DatabaseColumnValues (db)

  for i = 1, cols do

    print (names [i], "=", values [i])

  end -- for each column

  rc = DatabaseStep (db)  -- read next row

end -- while loop

-- finished with the statement

DatabaseFinalize (db)

You should really check the return code from DatabasePrepare in case you have an error in the SQL statement, as shown above for DatabaseExec.

Example using the Lua interface

require "tprint"

-- make in-memory database

db = sqlite3.open_memory()

-- make a table for testing

db:exec  [[

          CREATE TABLE mobs (name, class, hp);

          INSERT INTO mobs VALUES("Naga", "mage", 666);

          INSERT INTO mobs VALUES("Wolf", "beast", 42);

          INSERT INTO mobs VALUES("Guard", "warrior", 100);

       ]]

-- prepare a SELECT statement

local stmt = db:prepare ("SELECT * FROM mobs")

-- loop until we get everything

while true do

  local result = stmt:step ()

  -- exit loop if done

  if result == sqlite3.DONE then

    break

  end -- if done

  -- should have ROW result

  assert (result == sqlite3.ROW, "Row not found")

  -- get all values into a table

  local row = stmt:get_named_values()

  -- display them

  print (string.rep ("-", 20))

  tprint (row)

end -- while

-- done with this statement

stmt:finalize ()

-- finished with database

db:close ()

See Also ...

Topics

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: general=database)


Default triggers/aliases/timers/macros/colours

The "defaults" concept is intended to allow you to have a single set of triggers/aliases/timers/macros/colours that are shared between many worlds. If you check "Override with default ..." in the appropriate part of the configuration interface, then existing items are discarded the next time the world is opened and replaced by the default ones, as described below.

This was added before plugins were added to MUSHclient, it is more flexible these days to put "shared" triggers etc. into a plugin and load that plugin into the worlds that need to share them.

To set up defaults to be shared across multiple worlds:

a) Open your favourite world, and then save as individual files your:

•	Colours

•	Triggers

•	Aliases

•	Macros

•	Timers

(there is a "save" button on each configuration screen to do this)

You do not need to do them all. For instance, if you only want to share colours, then only save the colours.

b) Use File -> Preferences -> Defaults to select the files you saved in the above step

c) Also select your preferred input and output font.

d) For all worlds that are to share these saved files, open that world, and then using the appropriate configuration screen (eg. colours, triggers) check the box "override with default".

From then on, the *next* time you open that world, it will load the world, and then load (and thus overwrite) the settings you have checked as "override with default".

Also, any new worlds will use the default settings, thus new worlds will quickly take on your default characteristics.

Note that the defaults, when loaded, *overwrite* your existing settings, so that the existing triggers, colours etc. are *lost*. If you really want to keep the existing settings, then you should save the world file under a different name (thus preserving the original).

See Also ...

Topics

 Aliases

 Colour management

 Timers

 Triggers

(Help topic: general=defaults)


Getting started

If you just want to get started playing on a MUD, go to the Connection menu and choose "Quick Connect".

Then type in the MUD name, IP address, and port, click OK and you will be connected. Have fun!

Help

When any window or dialog is open, press F1 for help on that window.

To see what the various commands do (menus, and buttons on the button-bar below the menu) press Shift+F1. The cursor will change into a cursor with a question-mark next to it. Then select the menu or button you are interested in, and the appropriate help will be shown.

See Also ...

Topics

 Activity window

 Aliases

 Chat system

 Program features

 Speed walking

 Timers

 Triggers

Commands

 GettingStarted (Help on getting started with MUSHclient)

 Introduction (Getting Started)

Dialogs

 Main MUSHclient window

 MUSHclient

 Quick Connect

(Help topic: general=starting)


Groups

Triggers, aliases and timers can be placed into "groups".

This is simply a convenient way of managing a group of them for the purpose of:

•	Enabling an entire group of triggers, aliases or timers

•	Disabling an entire group

•	Deleting an entire group

You can make up any name you like for the group, it is just for your convenience.

See Also ...

Topics

 Aliases

 Timers

 Triggers

Functions

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

(Help topic: general=group)


Info bar - programmable information bar

This is an additional "information bar" initially created above the normal MUSHclient status line. It uses the full screen width, and can be used to show information relevant to what you are doing (eg. current hit points).

The info bar has the following characteristics:

•	Shared between all worlds

•	Can only be updated from scripting

•	Can have multiple fonts, multiple colours, multiple font sizes and styles

•	Can be undocked and moved

•	Can be hidden or shown (from a script, or from the View menu)

To access the info bar from scripting you can use the script routines described below.

Using world.Info to add text to the info bar does not replace existing content. The intention is that you initially use "InfoClear" to remove earlier content, then InfoFont and InfoColour to set up the info bar for the correct font and colour for the *next* piece of text. Then use world.Info to write text in the new font and colour.

See Also ...

Command

 InfoBar (Show or hide the info bar)

Dialog

 Info bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: general=infobar)


Information

There are various ways of getting information about the current world.

•	The configuration "info" window shows details including line counts and memory used

•	You can find out what version of Windows Sockets is in use from the File Menu -> Windows Socket Information

•	You can find the text attributes of the current selection

•	Various script routines return information - see the list below.

See Also ...

Commands

 Info (Shows information about this world)

 TextAttributes (Gets the attributes of the first character of the selection)

 WindowsSocketInformation (Information about the version of Winsock in use)

Dialog

 Windows Sockets information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: general=info)


Keypad navigation

If enabled, you can use the numeric keypad (usually on the right-hand side of the keyboard) to execute any commands you like.

The default is for direction commands, such as "8" for North, "2" for South, and so on, however you can configure the keys to be anything you like.

The text you specify is sent through the normal command processor, so the numeric keypad can be an alias, which might send a script, for example.

You can also specify actions if you hold down the Control key (eg. Ctrl+2).

See Also ...

Topics

 Aliases

 Macro keys

Commands

 ConfigureKeypad (Sets numeric keypad options)

 CtrlKeypad0 (Executes a user-defined numeric keypad action.)

 CtrlKeypad1 (Executes a user-defined numeric keypad action.)

 CtrlKeypad2 (Executes a user-defined numeric keypad action.)

 CtrlKeypad3 (Executes a user-defined numeric keypad action.)

 CtrlKeypad4 (Executes a user-defined numeric keypad action.)

 CtrlKeypad5 (Executes a user-defined numeric keypad action.)

 CtrlKeypad6 (Executes a user-defined numeric keypad action.)

 CtrlKeypad7 (Executes a user-defined numeric keypad action.)

 CtrlKeypad8 (Executes a user-defined numeric keypad action.)

 CtrlKeypad9 (Executes a user-defined numeric keypad action.)

 CtrlKeypadDash (Executes a user-defined numeric keypad action.)

 CtrlKeypadDot (Executes a user-defined numeric keypad action.)

 CtrlKeypadPlus (Executes a user-defined numeric keypad action.)

 CtrlKeypadSlash (Executes a user-defined numeric keypad action.)

 CtrlKeypadStar (Executes a user-defined numeric keypad action.)

 Keypad0 (Executes a user-defined numeric keypad action.)

 Keypad1 (Executes a user-defined numeric keypad action.)

 Keypad2 (Executes a user-defined numeric keypad action.)

 Keypad3 (Executes a user-defined numeric keypad action.)

 Keypad4 (Executes a user-defined numeric keypad action.)

 Keypad5 (Executes a user-defined numeric keypad action.)

 Keypad6 (Executes a user-defined numeric keypad action.)

 Keypad7 (Executes a user-defined numeric keypad action.)

 Keypad8 (Executes a user-defined numeric keypad action.)

 Keypad9 (Executes a user-defined numeric keypad action.)

 KeypadDash (Executes a user-defined numeric keypad action.)

 KeypadDot (Executes a user-defined numeric keypad action.)

 KeypadPlus (Executes a user-defined numeric keypad action.)

 KeypadSlash (Executes a user-defined numeric keypad action.)

 KeypadStar (Executes a user-defined numeric keypad action.)

Dialog

 Configure numeric keypad

(Help topic: general=keypad)


Logging

You can "log" sessions, which means to save them to disk in a text file.

You can use aliases and triggers to exclude certain things from the log file (such as spammy information that is not relevant to the log).

You can also log in HTML if you like, which preserves the colours of the original session.

See Also ...

Commands

 ConfigureLogging (Sets logging options)

 LogSession (Writes the game session out to a text file)

Dialogs

 Log game session

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: general=logging)


Lua base functions

Lua base functions and variables

These are the "base" functions in Lua (that is, those that are not in library tables).

_G

Variable which is the global environment table. (_G._G == _G)

You cannot change the environment by assigning to _G, use setfenv instead.

_VERSION

A global variable that is a string containing the current Lua interpreter version.

print (_VERSION) --> Lua 5.1

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: general=lua_base)


Lua bc (big number) functions

Big number (bc) functions

This library lets you do arbitrary precision (big number) arithmetic.

Big numbers have a metatable attached to them so you can add, subtract, divide, multiply, raise to a power, and compare them in the usual way. You can also use bc.add, bc.sub, bc.div, bc.mul, and bc.pow to do the same operations.

Thus, the following two forms are equivalent:

bc.digits (20)

a = bc.number (2)

print (bc.sqrt (a))  --> 1.41421356237309504880

print (a:sqrt ())    --> 1.41421356237309504880

Also see:

•	The math library for other mathematical operations.

•	The bit library for bitwise operations.

Some useful constants are:

 e = 2.7182818284590452353602874713526624977572470936999595749669676277240766303535

pi = 3.1415926535897932384626433832795028841971693993751058209749445923078164062862

radians = degrees * pi / 180

See Also ...

Topics

 Lua base functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: general=lua_bc)


Lua bit manipulation functions

Bit manipulation functions

The Lua language does not contain native support for bit-wise manipulation of numbers (and, or, exclusive or etc.)

MUSHclient has a few simple extensions that permit that.

They are in the library (table) "bit".

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: general=lua_bit)


Lua coroutine functions

Lua coroutine functions

These are the functions in the "coroutine" table.

Coroutines are a very powerful way of splitting execution of a function up until some event occurs (for example, a timer fires, or input arrives). The function chooses when to "yield" execution.

The yield / resume sequence allows variables to be passed back and forward between the thread and the caller. For example the thread can yield with an argument which tells the caller why it yielded, and the caller can resume with an argument telling the thread why it was resumed.

Personally I wouldn't use coroutine.wrap, but stick to something like this:

•	Create a new thread using coroutine.create. At this stage it is not yet running.

•	Commence executing the function in the thread with coroutine.resume, passing any initial arguments required.

•	The thread yields execution, if necessary, using coroutine.yield, passing arguments back to be returned by coroutine.resume. These arguments could indicate the reason for yielding.

•	The main script resumes the thread when it is ready to do so, calling coroutine.resume again. This time arguments passed to coroutine.resume are returned as results from the coroutine.yield call. These arguments could indicate the reason the thread is resuming (eg. data received, timeout and so on).

•	The previous 2 steps are repeated until it is time for the function to return, effectively terminating the thread.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.resume (Start or resume a thread)

 coroutine.running (Returns the running coroutine)

 coroutine.status (Returns the status of a thread)

 coroutine.wrap (Creates a thread and returns a function to resume it)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: general=lua_coroutines)


Lua debug functions

Lua debug functions

These are the functions in the "debug" table. The debug functions are not optimized for speed, they are designed to help debug your programs.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: general=lua_debug)


Lua io functions

Lua io functions

These are the functions in the "io" table.

Implicit operations (eg. io.read, io.write) use the standard file descriptors io.stdin, io.stdout, and io.stderr.

You can operate on other files by getting a "file descriptor" from io.open,  io.input, or io.output, and using that.

Note the syntactical difference, that you follow a file descriptor by a colon, eg. f:close ()

Also see the description for the "os" table for operating system functions that do things like remove and rename files.

The operations whose name start with "f:" (such as f:read) depend on having an open file handle returned from io.open, io.input, or io.output.

Note the colon after the f, as this indicates that the file handle (userdata from the open) is to be supplied as the first argument to the function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: general=lua_io)


Lua LPEG library

LPeg is a pattern-matching library for Lua, based on Parsing Expression Grammars (PEGs).

 For a more formal treatment of LPeg, as well as some discussion about its implementation, see:

http://www.inf.puc-rio.br/~roberto/docs/peg.pdf  (A Text Pattern-Matching Tool based on Parsing Expression Grammars.)

Following the Snobol tradition, LPeg defines patterns as first-class objects. That is, patterns are regular Lua values (represented by userdata). The library offers several functions to create and compose patterns. With the use of metamethods, several of these functions are provided as infix or prefix operators. On the one hand, the result is usually much more verbose than the typical encoding of patterns using the so called regular expressions (which typically are not regular expressions in the formal sense). On the other hand, first-class patterns allow much better documentation (as it is easy to comment the code, to use auxiliary variables to break complex definitions, etc.) and are extensible, as we can define new functions to create and compose patterns.

For a quick glance of the library, the following table summarizes its basic operations for creating patterns:

Operator	Description

•	lpeg.P(string) : Matches string literally

•	lpeg.P(number) : Matches exactly number characters

•	lpeg.S(string)	  : Matches any character in string (Set)

•	lpeg.R("xy")	: Matches any character between x and y (Range)

•	patt^n	: Matches at least n repetitions of patt

•	patt^-n	: Matches at most n repetitions of patt

•	patt1 * patt2	: Matches patt1 followed by patt2

•	patt1 + patt2	: Matches patt1 or patt2 (ordered choice)

•	patt1 - patt2	: Matches patt1 if patt2 does not match

•	-patt	: Equivalent to ("" - patt)

•	#patt	: Matches patt but consumes no input

As a very simple example, lpeg.R("09")^1 creates a pattern that matches a non-empty sequence of digits. As a not so simple example, -lpeg.P(1) (which can be written as lpeg.P(-1) or simply -1 for operations expecting a pattern) matches an empty string only if it cannot match a single character; so, it succeeds only at the subject's end.

In addition to the functions documented here, some arithmetic operators have special effects on patterns:

#patt

Returns a pattern that matches only if the input string matches patt, but without consuming any input, independently of success or failure. (This pattern is equivalent to &patt in the original PEG notation.)

When it succeeds, #patt produces all captures produced by patt.

-patt

Returns a pattern that matches only if the input string does not match patt. It does not consume any input, independently of success or failure. (This pattern is equivalent to !patt in the original PEG notation.)

As an example, the pattern -lpeg.P(1) matches only the end of string.

This pattern never produces any captures, because either patt fails or -patt fails. (A failing pattern never produces captures.)

patt1 + patt2

Returns a pattern equivalent to an ordered choice of patt1 and patt2. (This is denoted by patt1 / patt2 in the original PEG notation, not to be confused with the / operation in LPeg.) It matches either patt1 or patt2, with no backtracking once one of them succeeds. The identity element for this operation is the pattern lpeg.P(false), which always fails.

If both patt1 and patt2 are character sets, this operation is equivalent to set union.

patt1 - patt2

Returns a pattern equivalent to !patt2 patt1. This pattern asserts that the input does not match patt2 and then matches patt1.

If both patt1 and patt2 are character sets, this operation is equivalent to set difference. Note that -patt is equivalent to "" - patt (or 0 - patt). If patt is a character set, 1 - patt is its complement.

patt1 * patt2

Returns a pattern that matches patt1 and then matches patt2, starting where patt1 finished. The identity element for this operation is the pattern lpeg.P(true), which always succeeds.

(LPeg uses the * operator [instead of the more obvious ..] both because it has the right priority and because in formal languages it is common to use a dot for denoting concatenation.)

patt^n

If n is nonnegative, this pattern is equivalent to pattn patt*. It matches at least n occurrences of patt.

Otherwise, when n is negative, this pattern is equivalent to (patt?)-n. That is, it matches at most -n occurrences of patt.

In particular, patt^0 is equivalent to patt*, patt^1 is equivalent to patt+, and patt^-1 is equivalent to patt? in the original PEG notation.

In all cases, the resulting pattern is greedy with no backtracking (also called a possessive repetition). That is, it matches only the longest possible sequence of matches for patt.

patt / string

Creates a string capture. It creates a capture string based on string. The captured value is a copy of string, except that the character % works as an escape character: any sequence in string of the form %n, with n between 1 and 9, stands for the match of the n-th capture in patt. The sequence %0 stands for the whole match. The sequence %% stands for a single %.

patt / table

Creates a query capture. It indexes the given table using as key the first value captured by patt, or the whole match if patt produced no value. The value at that index is the final value of the capture. If the table does not have that key, there is no captured value.

patt / function

Creates a function capture. It calls the given function passing all captures made by patt as arguments, or the whole match if patt made no capture. The values returned by the function are the final values of the capture. In particular, if function returns no value, there is no captured value.

Grammars

With the use of Lua variables, it is possible to define patterns incrementally, with each new pattern using previously defined ones. However, this technique does not allow the definition of recursive patterns. For recursive patterns, we need real grammars.

LPeg represents grammars with tables, where each entry is a rule.

The call lpeg.V(v) creates a pattern that represents the nonterminal (or variable) with index v in a grammar. Because the grammar still does not exist when this function is evaluated, the result is an open reference to the respective rule.

A table is fixed when it is converted to a pattern (either by calling lpeg.P or by using it wherein a pattern is expected). Then every open reference created by lpeg.V(v) is corrected to refer to the rule indexed by v in the table.

When a table is fixed, the result is a pattern that matches its initial rule. The entry with index 1 in the table defines its initial rule. If that entry is a string, it is assumed to be the name of the initial rule. Otherwise, LPeg assumes that the entry 1 itself is the initial rule.

As an example, the following grammar matches strings of a's and b's that have the same number of a's and b's:

equalcount = lpeg.P{

  "S";   -- initial rule name

  S = "a" * lpeg.V"B" + "b" * lpeg.V"A" + "",

  A = "a" * lpeg.V"S" + "b" * lpeg.V"A" * lpeg.V"A",

  B = "b" * lpeg.V"S" + "a" * lpeg.V"B" * lpeg.V"B",

} * -1

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: general=lua_lpeg)


Lua math functions

Lua math functions

These are the functions in the "math" table.

Trigonometry functions use radians. To convert degrees to radians use math.rad.

Or, to look at it another way:

radians = degrees * math.pi / 180

pi

The variable math.pi gives you the value of pi.

pi = math.pi

e

To use e in an expression you can use the math.exp function.

e = math.exp (1)

See also the "bc" (big number) library for functions that work with numbers to arbitrary precision.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: general=lua_math)


Lua os functions

Lua os functions

These are the functions in the "os" table. Some of these functions are disabled by default in the MUSHclient "Lua sandbox". Check that out if you plan to use the "os" functions.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: general=lua_os)


Lua package functions

Lua package functions

These are the functions in the "package" table.

The package manager is designed for scripters who need to use multiple files and load them in a consistent way.

See also the "require" and "module" functions in the Lua base functions page.

Some of the items in the package library are strings and tables, rather than functions to be called.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: general=lua_package)


Lua PCRE regular expression functions

PCRE regular expression functions (rex)

The functionality of the PCRE (Perl Compatible Regular Expression) library is available to Lua scripts.

This is exactly the same regular expression matching that is done in triggers and alias matching.

First you create (compile) a regular expression into a rex object using rex.new.

Once the object is compiled you can repeatedly match it against target strings using re:match, re:gmatch, and re:exec (where "re" is the name of the compiled object).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:exec (Matches a regexp to a string, returning offsets)

 re:gmatch (Matches a regexp to a string, applying a function)

 re:match (Matches a regexp to a string)

 rex.flags (Returns a table of PCRE flags)

 rex.new (Compiles a regular expression)

(Help topic: general=lua_rex)


Lua script extensions

MUSHclient has some scripting extensions which are only available to Lua scripting. This page describes them.

Lua "sandbox"

To help block out dangerous functions, for example:

os.execute "del mushclient.exe"

... MUSHclient has a 'preliminary script' box in its Global Preferences -> Lua section.

Into this you can place code that disables some 'dangerous' functions (like 'os') by setting them to nil.

The code in this box is executed every time the Lua script engine is instantiated, in other words for every world, and every plugin.

You can modify the sandbox code to remove all restrictions, add more, or fine-tune them to your requirements. For example, if you wanted to use os.date and os.time (and others), but not os.execute, os.remove or os.rename, you could use:

os.execute = nil  -- no executing OS commands

os.remove = nil   -- no removing files

os.rename = nil   -- no renaming files

'print' function

To make it easier to use Lua examples in MUSHclient, the function "print" is defined to effectively call the world "Note" function. However, unlike Note, print adds a space between each argument (like the Lua "print" does).

eg.

Note "hello, world"

print "hello, world"    --> does the same thing

Note (1, 2, 3) --> 123

print (1, 2, 3) --> 1 2 3

world functions available from global scope

Although the normal MUSHclient script functions are defined in the "world" table, MUSHclient adds a metatable to the _G table and uses the __index entry to make the script functions available at global scope.

Put another way, you can either write:

world.Note "hello, world"  --> calls Note function in world table

Note "hello, world"        --> does the same thing

Both methods call the world.Note script function.

If you wish to change the behaviour of an inbuilt script function you must replace the world.XXX version (eg. change world.Note) rather than simply replacing the global version.

'check' function

Many script functions return error codes (see the error_code table described below). A quick way of checking that the function has succeeded is to wrap the 'check' function around it.

For example, instead of:

DoAfter (10, "eat food")

you could do this:

check (DoAfter (10, "eat food"))

This raises an error (and shows the appropriate error message) if the function fails. Note that this is not relevant to all functions, only those which are documented to return eOK on success, and some other code on failure.

Constants

To make it easier to write scripts, MUSHclient's Lua interface has various built-in tables of constants.

Trigger flags for AddTrigger

These are in the 'trigger_flag' table.

print (trigger_flag.OmitFromOutput) --> 4

Trigger flags for AddAlias

These are in the 'alias_flag' table.

print (alias_flag.AliasQueue) --> 4096

Trigger flags for AddTimer

These are in the 'timer_flag' table.

print (timer_flag.OneShot) --> 4

Custom colour flags for AddTrigger

These are in the 'custom_colour' table.

print (custom_colour.NoChange) --> -1

Error codes - map error names to numbers

These are in the 'error_code' table.

You can use these to check individual error codes.

eg.

if AddTimer (blah blah blah) ==

     error_code.eTimerAlreadyExists  then

  error ("That timer already exists")

end

print (error_code.eBadRegularExpression) --> 30021

Also see above about the 'check' function.

Error codes - map error codes to descriptions

These are in the 'error_desc' table.

You can use these to give meaningful error messages.

eg.

status = AddTimer ("a", 0, 0, 0, 0, 0)

if status ~= error_code.eOK  then

  error (error_desc [status]) -->  Time given to AddTimer is invalid

end

Colour names - map colour picker names to RGB values

These are in the 'colour_names' table.

You can use these to look up colour names (eg. "red") and find the corresponding RGB value.

Extended colour codes - map colour selector numbers to RGB values

These are in the 'extended_colours' table.

You can use these to see what the RGB equivalent is for the 256 extended colours (keyed by 0 to 255).

Send-to codes - map scripted "send" names to a number

These are in the 'sendto' table.

You can use these to make functions like DoAfterSpecial more self-documenting. For example, instead of sending to '12', you can send to 'sendto.script'.

eg.

DoAfterSpecial (5, "Sound ('ding.wav')",  sendto.script)

Miniwindow constants

These are in the 'miniwin' table.

You can use these to make functions like WindowCreate, WindowRectOp, WindowCircleOp etc. more self-documenting. For example, instead of doing WindowRectOp action 1, you can use 'miniwin.rect_frame'.

eg.

WindowRectOp (win, miniwin.rect_frame, 20, 20, 70, 70, ColourNameToRGB("blue"))

progress

This provides functionality for displaying a "progress" dialog box during lengthy operations.

First you create the progress dialog with:

progress.new (description)

That returns a userdata item that you can then use in subsequent operations:

dlg:status (msg) --> set a status message (eg. "processing 'foo' ")

dlg:range (low, high) --> sets the range of operations (eg. 1 to 100)

dlg:position (pos)  --> sets where we are in the range (eg. 80)

dlg:checkcancel ()  --> returns true if the user clicked on the cancel button

dlg:setstep (amount)  --> sets the step amount (eg. 5)

dlg:step ()  --> increase the position by the step amount

dlg:close ()  --> dismiss the progress dialog

Example of use:

local dlg = progress.new ("Loading things ...")

dlg:range (0, 3)  --> 3 steps

dlg:setstep (1)  --> step 1 per step

dlg:status ("Processing foo")  --> first step

dlg:step ()

-- do something lengthy here

dlg:status ("Processing bar")  --> second step

dlg:step ()

-- do something lengthy here

dlg:status ("Processing fruit")  --> third step

dlg:step ()

-- do something lengthy here

dlg:close ()  --> all done

The dialog box is a "modal" dialog, so make sure you arrange to close it, even on a script error, or it will lock out attempts to use the GUI interface. If necessary, use "pcall" on whatever it is you do while the dialog is open.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

 Scripting functions list

(Help topic: general=lua)


Lua SQLite (database) interface

LuaSQLite 3 is a thin wrapper around the public domain SQLite3 database engine.

The lsqlite3 module supports the creation and manipulation of SQLite3 databases. The exported functions are called with prefix sqlite3. However, most sqlite3 functions are called via an object-oriented interface to either database or SQL statement objects.

This documentation does not attempt to describe how SQLite3 itself works, it just describes the Lua binding and the available functions.

For more information about the SQL features supported by SQLite3 and details about the syntax of SQL statements and queries, please see the SQLite3 documentation http://www.sqlite.org/.

Using some of the advanced features (how to use callbacks, for instance) will require some familiarity with the SQLite3 API.

General technique

•	Open the database with either sqlite3.open or sqlite3.open_memory

•	Execute "action" SQL statements with db:exec

•	To query data from the database:

•	Prepare an SQL statement with db:prepare

•	Get column names with stmt:get_names or similar

•	Step through each row with stmt:step

•	Get column values with stmt:get_values or similar

•	After all rows are extracted, finalize the statement with stmt:finalize

•	Close the database with db:close

Numerical error and result codes

The following constants are defined by module sqlite3:

  OK: 0          ERROR: 1       INTERNAL: 2    PERM: 3        ABORT: 4

  BUSY: 5        LOCKED: 6      NOMEM: 7       READONLY: 8    INTERRUPT: 9

  IOERR: 10      CORRUPT: 11    NOTFOUND: 12   FULL: 13       CANTOPEN: 14

  PROTOCOL: 15   EMPTY: 16      SCHEMA: 17     TOOBIG: 18     CONSTRAINT: 19

  MISMATCH: 20   MISUSE: 21     NOLFS: 22      FORMAT: 24     RANGE: 25

  NOTADB: 26     ROW: 100       DONE: 101

For details about their exact meaning please see the SQLite3 documentation http://www.sqlite.org/.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: general=lua_sqlite3)


Lua string functions

Lua string functions

These are the functions in the "string" table.

Indices, where used, start at 1 for the first character (not zero). Negative numbers count from the right, so -1 is the last character, -2 the second last, and so on.

All strings have a metatable added to them by Lua with an __index entry pointing to the string table. What this means is that you can write string function calls in two ways:

s = "hello, world"

string.len (s) --> 12

s:len ()       --> 12

The second version is shorter as the word "string" is implied. Note the colon after the s, not a dot.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: general=lua_string)


Lua syntax

Lua general syntax

This section summarizes the syntax of Lua.

For more details see the online Programming In Lua book:

http://www.lua.org/pil/

Note that Lua is case-sensitive. Thus TRUE and true are different things.

There are a lot of examples and discussions in the Lua part of the MUSHclient forum:

http://www.mushclient.com/lua

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua keywords/topics

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: general=lua_syntax)


Lua table functions

Lua table functions

These are the functions in the "table" table.

Tables are collections of key/value pairs, where both the key and the value can be any Lua data type, except nil.

Tables are indexed by the key, so if you know the key you can quickly retrieve the value. If you don't know the keys you can search the table using the "pairs" or "ipairs" functions.

Since keys and values can be any data type (except nil) it follows that tables can contain other tables.

A table's size (which is only relevant for numerically-indexed tables) is one less than the first integer index with a nil value. If the table has "holes" in it - that is, numeric keys with gaps in the sequence - then the table size is not guaranteed to be the the last gap. Lua does a binary search to try to find a gap, it does not necessarily find the first or last one.

If you are planning to treat your tables as vectors (that is, with numeric keys and a size) then we recommend that you do not allow gaps in the sequence.

If you want to know if a table is empty, or not, you can test:

if next (t) == nil then

  -- table t is empty

end -- if empty

The behaviour of tables can be modified somewhat by attaching a "metatable" to them with the setmetatable function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: general=lua_tables)


Lua utilities

The "utils" (utilities) library offers various helpful utility functions, including:

•	Bringing a different program window to the front

•	Compression and decompression

•	Hashing using various methods

•	Base-64 encoding and decoding

•	Dialog boxes for asking questions and making announcements

•	Dialog boxes for choosing from lists and combo-boxes

•	Executing Windows "shell" commands

•	File-picker dialog box

•	Spell-checker "misspelt word" dialog box

•	Spell-checker utilities such as metaphone and edit distance

•	Conversion of strings to and from hexadecimal form

•	Read disk directory into a table

•	Information about MUSHclient environment (directory names)

•	List of world function names

•	List of plugin callback function names

•	Split a string into a table, at delimiters (eg. comma-delimited)

•	UTF-8 (Unicode) encoding, decoding and checking

•	XML parser

See also the following libraries:

•	Perl-compatible regular expressions library (rex)

•	Big number (arbitrary precision) library (bc)

•	Bit management library (bit)

You can also use the luacom library (to access COM objects). To do this you must first "require" it, like this:

require "luacom"

There is documentation about luacom in a PDF document in the MUSHclient docs subdirectory.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: general=lua_utils)


Macro keys

You can use the macros configuration to define "macros" - these are really user-defined keystrokes.

Macros are sent through the normal command interpreter, so they can consist of aliases, script commands, speedwalks and so forth.

As an extension, from version 3.53 onwards you can also define your own "accelerator" keys, which is another fancy word for "extended macros".

See the "Accelerator" function for more information.

Unlike ordinary macros, which are fixed to certain predefined keystroke combinations, the Accelerator function lets you define any combination of keys (within reason), including redefining the behaviour of existing keystrokes (eg. Ctrl+N for New Document could become something else).

Any accelerators which have been defined with the Accelerator function will hide a corresponding macro from being shown in the GUI macro configuration screen, so as to avoid confusion about what the keystroke actually does.

Hint

To do more elaborate things (like expanding variables, running scripts) enter a nonsense word as what to send, and then make an alias to "catch" that word, and do the extra processing in the alias. One way of doing this is to use the Edit -> Generate Unique ID menu item to generate a unique word, like this:

381e051a828fb201b6914699

This is unlikely to be something you would normally want to type into the MUD. Then make an alias to match on "381e051a828fb201b6914699" (or whatever word you choose) and make the alias do things like expand variables, call scripts, etc.

See Also ...

Topics

 Aliases

 Keypad navigation

Commands

 AltA (Executes a user-defined macro.)

 AltB (Executes a user-defined macro.)

 AltJ (Executes a user-defined macro.)

 AltK (Executes a user-defined macro.)

 AltL (Executes a user-defined macro.)

 AltM (Executes a user-defined macro.)

 AltN (Executes a user-defined macro.)

 AltO (Executes a user-defined macro.)

 AltP (Executes a user-defined macro.)

 AltQ (Executes a user-defined macro.)

 AltR (Executes a user-defined macro.)

 AltS (Executes a user-defined macro.)

 AltT (Executes a user-defined macro.)

 AltU (Executes a user-defined macro.)

 AltV (Executes a user-defined macro.)

 AltX (Executes a user-defined macro.)

 AltY (Executes a user-defined macro.)

 AltZ (Executes a user-defined macro.)

 ConfigureMacros (Sets macro options)

 East (Executes a user-defined macro.)

 Look (Executes a user-defined macro.)

 MacroCtrlF10 (Executes a user-defined macro.)

 MacroCtrlF11 (Executes a user-defined macro.)

 MacroCtrlF12 (Executes a user-defined macro.)

 MacroCtrlF2 (Executes a user-defined macro.)

 MacroCtrlF3 (Executes a user-defined macro.)

 MacroCtrlF5 (Executes a user-defined macro.)

 MacroCtrlF7 (Executes a user-defined macro.)

 MacroCtrlF8 (Executes a user-defined macro.)

 MacroCtrlF9 (Executes a user-defined macro.)

 MacroF10 (Executes a user-defined macro.)

 MacroF11 (Executes a user-defined macro.)

 MacroF12 (Executes a user-defined macro.)

 MacroF2 (Executes a user-defined macro.)

 MacroF3 (Executes a user-defined macro.)

 MacroF4 (Executes a user-defined macro.)

 MacroF5 (Executes a user-defined macro.)

 MacroF7 (Executes a user-defined macro.)

 MacroF8 (Executes a user-defined macro.)

 MacroF9 (Executes a user-defined macro.)

 MacroShiftF10 (Executes a user-defined macro.)

 MacroShiftF11 (Executes a user-defined macro.)

 MacroShiftF12 (Executes a user-defined macro.)

 MacroShiftF2 (Executes a user-defined macro.)

 MacroShiftF3 (Executes a user-defined macro.)

 MacroShiftF4 (Executes a user-defined macro.)

 MacroShiftF5 (Executes a user-defined macro.)

 MacroShiftF6 (Executes a user-defined macro.)

 MacroShiftF7 (Executes a user-defined macro.)

 MacroShiftF8 (Executes a user-defined macro.)

 MacroShiftF9 (Executes a user-defined macro.)

 North (Executes a user-defined macro.)

 South (Executes a user-defined macro.)

 Take (Executes a user-defined macro.)

 Up (Executes a user-defined macro.)

 West (Executes a user-defined macro.)

 Whisper (Executes a user-defined macro.)

Dialogs

 Edit macro

 Macros

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: general=macros)


MiniWindows

MUSHclient from version 4.34 onwards now has "floating miniwindows" which appear on top of, or to the side of, the main output window. As these are part of the main window, if you move or resize the main window, the extra windows automatically move with it.

You can use the TextRectangle function to move the main scrolling output window away from the edges of the window, so that miniwindows can be placed above, below, or to the sides of the text, without overlapping it.

•	Miniwindows are created and manipulated purely by script commands, generally intended to be inside plugins.

•	You can have any number of miniwindows at once. Each one has a name which is used by the script to refer to it. Your only limitation would be available screen space, and your imagination. Names are case-sensitive.

•	Miniwindows do not necessarily have to be visible. Thus you could be adding to a miniwindow (such as your inventory) during combat, when you might not want to see it. Later, you can show it, and its most recent contents will be displayed.

•	Each miniwindow is rectangular in shape, and can be any size you like. They start off with a background colour you specify, however you can change that partly or completely by drawing in the window.

•	You can position the miniwindows whereever you want to, however there are various auto-positioning options, such as top left corner, middle of top of window, top right corner, and so on.

•	Miniwindows are drawn in an off-screen buffer (bitmap), and then automatically copied to the main output window, whenever the output window is redrawn. This provides fast, flicker-free operation.

•	Miniwindows can be drawn either above or below the normal output window text. Normally for a floating-style window you would want it above (and thus the text scrolls underneath it), however for some background information you can choose to have the text scroll over the miniwindow.

•	Miniwindows can capture mouse-down, mouse-move, and mouse-up events, in order to react to the player clicking on them. This can be used to implement hyperlinks, buttons, and "mouse-over" help.

•	Miniwindows can be resized and moved as desired.

•	Miniwindows can be drawn transparently, so that they can have holes in them, wherever the transparent colour appears.

•	Miniwindows can have any number of "hotspots" which are rectangular areas which react to mouse-over, mouse-down, and mouse-up events. Each hotspot has a "hotspot ID" which identifies it. Hotspot IDs are case-sensitive. Hotspots can optionally show "hover-over" text (eg. hints) to show what they are used for.

•	With the assistance of some scripting (see the "movewindow" module) you can arrange for miniwindows to be dragged around to any desired location.

See Also ...

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: general=miniwindows)


MUSHclient

Follow the links below for the main help topics ...

For online support, if your question is not answered here, please use the MUSHclient forum at our web site:

http://www.gammon.com.au/forum/

Topics

 Activity window

 Aliases

 Arrays

 Auto-mapper

 Chat system

 Colour management

 Commented softcode

 Database (SQLite)

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Info bar - programmable information bar

 Information

 Keypad navigation

 Logging

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Macro keys

 MiniWindows

 MXP - Mud Extension Protocol

 Notepad

 Notes

 Option setting and retrieval

 Plugins

 Program features

 Registration

 Regular Expressions

 Scripting

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Sending to the world

 Speed walking

 Spell checker

 Timers

 Triggers

 Utilities

 Variables

 World functions

Help file generated on Friday, March 29, 2019, 5:16 PM.

(Help topic: general=contents)


MXP - Mud Extension Protocol

What is MXP?

MXP stands for Mud Extension Protocol.

It is a method for MUD servers to specify formatting and content information which goes beyond the scope of what is available with ANSI escape codes. For instance, using MXP a server can designate a line as a room description, exit, hyperlink, and so on.

For example:

This word is <b>bold</b>.

<RoomDesc>This is a room description</RoomDesc>

MUSHclient support

MUSHclient supports most of the MXP features as documented in the MXP specs. When receiving MXP commands from a MUD you will probably see hyperlinks (that you can click on) and pop-up menus (by right-mouse clicking on a link).

Server support

Various MUDs now support MXP. Probably one of the best is in the Dawn Of Time server, which has extensive support. Various other MUDs also have MXP support.

See Also ...

Dialog

 MXP / Pueblo

(Help topic: general=mxp)


Notepad

MUSHclient has an internal notepad editor (similar to the Windows Notepad program).

This is useful for working on things whilst mudding. For example, you could type in a lengthy room description into a notepad window.

The notepad also lets you do useful conversions, like Unix to DOS, Base-64 encode/decode, quote forum codes, convert/unconvert HTML special characters.

You can also do find-and-replace.

There is a "bracket matcher" for finding the matching parenthesis in C code, or MUSHcode. This is configurable.

See Also ...

Commands

 ASCIIart (Generate ASCII art)

 CloseAllNotepadWindows (Closes all open notepad windows)

 CompleteFunction (Invokes a menu of function names that match a partially typed one)

 FindNextNotepad (Find Next)

 FindNotepad (Find)

 FlipToNotepad (Flips to related world window)

 GlobalReplace (Does a global find-and-replace on the selected text using string.gsub)

 GoToNotepadLine (Go To)

 NotesWorkArea (Opens a notepad window for working on long commands etc.)

Dialogs

 Choose notepad window

 Complete Function Name

 Global Replace

 Notepad window

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: general=notepad)


Notes

There are various script functions for making notes to yourself in the output window.

You can also set triggers, aliases and timers to "send to output" which will send the "send text" to the output window (effectively doing a note).

Notes can be in the default "world note" colour, or you can use scripts to make notes in any colour.

See Also ...

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: general=note)


Option setting and retrieval

Virtually every "world" option in MUSHclient can be set or queried using script routines, which lets you dynamically adjust the behaviour of the client as it is running.

See below for more information.

See Also ...

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: general=options)


Plugins

Plugins are self-contained collections of related triggers, aliases, timers, variables and script routines. They are distributed as a single file, and installed by simply clicking on 'add' in the plugins dialog.

They are intended to allow the distribution of extensions to MUSHclient functionality in a simple way, without having to have complex instructions about amending script files, adding triggers and so on.

Plugins can also save their 'state' (ie. remember variables) so that variables that are set in one session will be remembered in another. This happens on a per-plugin, per-world basis.

You can quickly generate your own plugins by using the Plugin Wizard, which creates a plugin from your existing triggers, timers, aliases, variables and scripts.

Plugins can be given a sequence number (in the plugin file) which controls the order in which plugins are evaluated, and thus which plugin gets the first chance to evaluate triggers, aliases, etc.

The default sequence is 5000. Lower sequenced plugins get evaluated before higher sequenced ones.

See Also ...

Topics

 Aliases

 Arrays

 Scripting

 Timers

 Triggers

 Variables

Commands

 Plugins (Shows plugins active for this world)

 PluginWizard (Invokes the plugin creation wizard)

Dialogs

 Global preferences - plugins

 Plugin wizard - Aliases

 Plugin wizard - Comments

 Plugin wizard - Description

 Plugin wizard - Name and Purpose

 Plugin wizard - Script

 Plugin wizard - Timers

 Plugin wizard - Triggers

 Plugin wizard - Variables

 Plugins

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: general=plugins)


Program features

Fast MUD/MUSH/MUCK/MOO client for Windows. Written in C++ for high speed and compact size.

Has large scrollback buffer, command history, aliases, triggers, timers, keypad-navigation, speed-walking, and auto-say.

Supports scripting in Lua, VBscript, Jscript, PerlScript and Python, recognizes ANSI color codes, has user-defined macros, spell checking, proxy server support, chat system, built-in editor, and logging.

Also supports MUD extensions MCCP (Mud Client Compression Protocol) and MXP (Mud eXtension Protocol).

You can write your own plugins in any of the four supported scripting languages, or use ones written by others which are supplied with the program, or appear on our web site.

Worlds

  •	Multiple worlds can be open at once

  •	You can automatically connect to a world (name and password)

  •	You can have multiple windows open per world

  •	Context-sensitive help is always available to explain how to use configuration screens, and other features.

  •	Details for an entire world, or just one of triggers/macros/aliases/colours/timers can be saved for re-use later.

  •	Supports MUD Client Compression Protocol (MCCP).

Output window

  •	Holds up to 500,000 previous lines in memory

  •	Fast scrolling back and forwards using keyboard or mouse

  •	Copy from output window for pasting into command window or elsewhere

  •	Can be frozen to review messages without them scrolling out of view

  •	Supports user-chosen font

  •	Supports user-chosen palette of colours

  •	Supports an additional 16 custom colours for triggers and other uses

  •	Recognises ANSI colours, hilight, inverse

  •	Automatic line wrapping at end of line so words are not chopped into two

  •	Selected messages from the MUD (eg. pages) can be displayed in a different colour to make them stand out (by using triggers)

Command (input) window

  •	Can be resized so lengthy commands can be entered

  •	Supports copy/cut/paste, arrow keys, home and end keys, and the mouse

  •	Last 5,000 commands entered are saved for recall and editing

  •	Previous commands can be viewed in a "command history" window for easy selection

  •	Commands can optionally be echoed in the output window

  •	Auto-completion allows partial words to be completed when you press <tab> based on a matching word in the output window.

  •	Spell-check automatically or on request

Logging

  •	Each world can log its output and (optionally) commands input

  •	Logging can commence automatically upon connection, appending to an existing log file if desired

  •	Logging can be filtered to remove pages, whispers etc.

  •	Filtering is controlled by using triggers

  •	Each log session can be prefixed and suffixed by identifying information (date, time etc.). The date/time can be automatically generated.

  •	Each log line can have a "line prefix" which may contain the date/time that line arrived

Notepad

  •	There is a custom "notepad" (text editor) for editing commands or any other purpose

  •	Notepad has spell-checker

  •	Notepad can do case conversions, and other conversions such as Unix to DOS

Macros (function keys)

  •	Up to 30 different keys can be used for single-keystroke entry of commands (F2 to F12, Ctrl+F2 to Ctrl+F12 and so on)

  •	Various other keystrokes are available for macros (Alt+A, Alt+B and others)

  •	You can use the numeric keypad also for single-keystroke movement

  •	Macro commands go through the command processor so they can call aliases, scripts, speedwalks etc.

Triggers

  •	Any number of "triggers" can be entered, per world. Triggers are used to match on output from the MUD, and then automatically perform a function (for example, page someone when they connect)

  •	Triggers can include wildcards (e.g. " * says * ") to match on variable text. The text matched on in the wildcard can be used in the response to the trigger.

  •	Alternatively, you can use "regular expressions" in triggers for precise matching

  •	Triggers can be set up to match the colour of incoming text

  •	Lines which activate a trigger can be displayed in a different colour, so you can use triggers to highlight certain types of game output.

  •	Individual words can be highlighted

  •	Lines which activate a trigger can also optionally play a sound file (a WAV file) so that you can use triggers to play sounds to alert you to certain events.

  •	Triggers can be used to omit certain types of displays from the log file (if one is open)

  •	Triggers can be used to copy the matched text back into the command (input) buffer for editing, if desired.

  •	Triggers can be used to send the matching text to the status line, or a notepad window, if desired.

  •	Triggers can call a script function.

Aliases

  •	Any number of "aliases" can be entered, per world. Aliases are a shorthand way of entering commands, for example: CLW could send "cure light wounds".

  •	Aliases can match the start of a command, anywhere in the command, or exactly the command by using wildcards. For example, if you set up an alias of "c" to mean "cure light wounds" and make it match exactly, then it will not clash with "close".

  •	Wildcards used in the alias can be used in the substitution text, so you can make aliases that can take "arguments"

  •	Aliases can expand out the contents of variables

  •	Aliases can match using regular expressions.

  •	Aliases can be used to omit the matching line from the log file, or the output window if desired

  •	Aliases can call a script function.

Timers

  •	Any number of "timers" can be entered, per world. Timers are used to cause things to happen at a particular time (eg. 9 pm) or an interval (eg. every 10 minutes).

  •	Timers can call a script function.

Speed walking

  •	You can optionally use speed walking to move quickly from one location to another.

Command stacking

  •	You can optionally use command stacking to enter more than one command per line.

Status line

  •	Status line shows name of active MUD, when input was last received, number of lines received and other useful things. The status line can be updated by a trigger or a script routine.

Activity window

  •	You can open an "activity" window which is useful when connected to multiple MUDs. It shows if there is activity (output from) a MUD which is not the current (frontmost) window. A single keystroke then switches to that window.

Numeric keypad

  •	You can use the numeric keypad for movement in the MUD (press 8 to go north, 2 to go south, 4 to go west, 6 to go east, and so on). The actual commands that are sent for each keystroke are customisable.

  •	You can also use an "alternate set" of keystrokes on the numeric keypad by holding down the Control key. This lets you have a second set of actions (perhaps for during a fight).

Scripting

  •	You can write scripts in Lua, Vbscript, JavaScript, PerlScript or Python.

  •	The Lua script DLL is supplied with MUSHclient, and is thus always available with any additional installations being necessary.

  •	Various script extensions available to Lua scripts allow things like dialog boxes for asking questions, and list boxes or combo boxes for making choices.

Mapping

  •	You can automatically map the direction you are going as you walk around.

Plugins

  •	Related groups of triggers/aliases/timers/variables and scripts can be saved as a "plugin" - a separate file.

  •	These can be easily generated using an inbuilt "plugin wizard".

  •	Plugins can be shared between different worlds, saving the need to repeat triggers etc. in multiple worlds, and also makes it easier to fix problems in one central place.

  •	Plugins can be distributed to friends without them needing to understand scripting or load individual triggers into their worlds.

International

  •	Support for languages other than English, by the provision to read messages, menus and dialog boxes from external files.

See Also ...

Topic

 Getting started

(Help topic: general=features)


Registration

MUSHclient is now distributed by the FreeWare method.

AUTHOR

MUSHclient has been written by Nick Gammon of Gammon Software Solutions.

Web page: http://www.gammon.com.au/

Contact/support: http://www.gammon.com.au/forum/

COPYRIGHT

MUSHclient is copyright 1995 - 2011 by Nick Gammon. All rights reserved worldwide.

MUSHclient is not in the public domain and Nick Gammon keeps its copyright.

PERMISSION TO DISTRIBUTE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

LIMITATION OF LIABILITY

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

(Help topic: general=register)


Regular Expressions

Perl-compatible Regular Expressions

This is an excerpt from the file RegularExpressions.txt that is supplied as part of the MUSHclient distribution.

If you enable regular expressions for things such as triggers, aliases, "recall" window, "find" command, and so on, this is the syntax that is used.

Note that Lua regular expressions use a different syntax, see the help page for "Lua String functions".

The syntax and semantics of the regular expressions supported by PCRE are described below. Regular expressions are also described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257), covers them in great detail. The description here is intended as reference documentation.

A regular expression is a pattern that is matched against a subject string from left to right. Most characters stand for themselves in a pattern, and match the corresponding characters in the subject. As a trivial example, the pattern

The quick brown fox

matches a portion of a subject string that is identical to itself. The power of regular expressions comes from the ability to include alternatives and repetitions in the pattern. These are encoded in the pattern by the use of meta-characters, which do not stand for themselves but instead are interpreted in some special way.

There are two different sets of meta-characters: those that are recognized anywhere in the pattern except within square brackets, and those that are recognized in square brackets. Outside square brackets, the meta-characters are as follows:

  \      general escape character with several uses

  ^      assert start of  subject  (or  line,  in  multiline mode)

  $      assert end of subject (or line, in multiline mode)

  .      match any character except newline (by default)

  [      start character class definition

  |      start of alternative branch

  (      start subpattern

  )      end subpattern

  ?      extends the meaning of (

        also 0 or 1 quantifier

        also quantifier minimizer

  *      0 or more quantifier

  +      1 or more quantifier

  {      start min/max quantifier

Part of a pattern that is in square brackets is called a "character class". In a character class the only meta-characters are:

  \      general escape character

  ^      negate the class, but only if the first character

  -      indicates character range

  ]      terminates the character class

 The following sections describe the use of each of the meta-characters.

Backslash

The backslash character has several uses. Firstly, if it is followed by a non-alphameric character, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes.

For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the following character would otherwise be interpreted as a meta- character, so it is always safe to precede a non-alphameric with "\" to specify that it stands for itself. In particular, if you want to match a backslash, you write "\\".

If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the pattern (other than in a character class) and characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be used to include a whitespace or "#" character as part of the pattern.

A second use of backslash provides a way of encoding non- printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pattern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary character it represents:

  \a     alarm, that is, the BEL character (hex 07)

  \cx    "control-x", where x is any character

  \e     escape (hex 1B)

  \f     formfeed (hex 0C)

  \n     newline (hex 0A)

  \r     carriage return (hex 0D)

  \t     tab (hex 09)

  \xhh   character with hex code hh

  \ddd   character with octal code ddd, or backreference

The precise effect of "\cx" is as follows: if "x" is a lower case letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B.

 After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case).

After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two digits after the initial zero if the character that follows is itself an octal digit.

The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is given later, following the discussion of parenthesized subpatterns.

Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for themselves. For example:

  \040   is another way of writing a space

  \40    is the same, provided there are fewer than 40 previous capturing subpatterns

  \7     is always a back reference

  \11    might be a back reference, or another way of writing a tab

  \011   is always a tab

  \0113  is a tab followed by the character "3"

  \113   is the character with octal code 113 (since there can be no more than 99 back references)

  \377   is a byte consisting entirely of 1 bits

  \81    is either a back reference, or a binary zero followed by the two characters "8" and "1"

Note that octal values of 100 or greater must not be introduced by a leading zero, because no more than three octal digits are ever read.

All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a different meaning (see below).

The third use of backslash is for specifying generic character types:

  \d     any decimal digit

  \D     any character that is not a decimal digit

  \s     any whitespace character

  \S     any character that is not a whitespace character

  \w     any "word" character

  \W     any "non-word" character

Each pair of escape sequences partitions the complete set of characters into two disjoint sets. Any given character matches one, and only one, of each pair.

A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl "word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale- specific matching is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some character codes greater than 128 are used for accented letters, and these are matched by \w.

These character type sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character to match.

The fourth use of backslash is for certain simple assertions. An assertion specifies a condition that has to be met at a particular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complicated assertions is described below. The backslashed assertions are

  \b     word boundary

  \B     not a word boundary

  \A     start of subject (independent of multiline mode)

  \Z     end of subject or newline at  end  (independent  of multiline mode)

  \z     end of subject (independent of multiline mode)

These assertions may not appear in character classes (but note that "\b" has a different meaning, namely the backspace character, inside a character class).

A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively.

The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described below) in that they only ever match at the very start and end of the subject string, whatever options are set. They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the startoffset argu- ment of pcre_exec() is non-zero, \A can never match. The difference between \Z and \z is that \Z matches before a newline that is the last character of the string as well as at the end of the string, whereas \z matches only at the end.

Circumflex and dollar

Outside a character class, in the default matching mode, the circumflex character is an assertion which is true only if the current matching point is at the start of the subject string. If the startoffset argument of pcre_exec() is non-zero, circumflex can never match. Inside a character class, circumflex has an entirely different meaning (see below).

Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it should be the first thing in each alternative in which it appears if the pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)

A dollar character is an assertion which is true only if the current matching point is at the end of the subject string, or immediately before a newline character that is the last character in the string (by default). Dollar need not be the last character of the pattern if a number of alternatives are involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class.

The meaning of dollar can be changed so that it matches only at the very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching time. This does not affect the \Z assertion.

The meanings of the circumflex and dollar characters are changed if the PCRE_MULTILINE option is set. When this is the case, they match immediately after and immediately before an internal "\n" character, respectively, in addition to matching at the start and end of the subject string. For example, the pattern /^abc$/ matches the subject string "def\nabc" in multiline mode, but not otherwise. Consequently, patterns that are anchored in single line mode because all branches start with "^" are not anchored in multiline mode, and a match for circumflex is possible when the startoffset argument of pcre_exec() is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.

Note that the sequences \A, \Z, and \z can be used to match the start and end of the subject in both modes, and if all branches of a pattern start with \A is it always anchored, whether PCRE_MULTILINE is set or not.

Full stop (period, dot)

Outside a character class, a dot in the pattern matches any one character in the subject, including a non-printing character, but not (by default) newline. If the PCRE_DOTALL option is set, then dots match newlines as well. The handling of dot is entirely independent of the handling of circumflex and dollar, the only relationship being that they both involve newline characters. Dot has no special meaning in a character class.

Square brackets

An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class, it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash.

A character class matches a single character in the subject; the character must be in the set of characters defined by the class, unless the first character in the class is a circumflex, in which case the subject character must not be in the set defined by the class. If a circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash.

For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters which are in the class by enumerating those that are not. It is not an assertion: it still consumes a character from the subject string, and fails if the current pointer is at the end of the string.

When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a caseful version would.

The newline character is never treated in any special way in character classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class such as [^a] will always match a newline.

The minus (hyphen) character can be used to specify a range of characters in a character class. For example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last character in the class.

It is not possible to have the literal character "]" as the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" and "-") followed by a literal string "46]", so it would match "W46]" or "-46]". However, if the "]" is escaped with a backslash it is interpreted as the end of range, so [W-\]46] is interpreted as a single class containing a range followed by two separate characters. The octal or hexadecimal representation of "]" can also be used to end a range.

Ranges operate in ASCII collating sequence. They can also be used for characters specified numerically, for example [\000-\037]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched caselessly, and if character tables for the "fr" locale are in use, [\xc8-\xcb] matches accented E characters in both cases.

The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can conveniently be used with the upper case character types to specify a more restricted set of characters than the matching lower case type. For example, the class [^\W_] matches any letter or digit, but not underscore.

All non-alphameric characters other than \, -, ^ (at the start) and the terminating ] are non-special in character classes, but it does no harm if they are escaped.

Posix character classes

Perl 5.6 (not yet released at the time of writing) is going to support the POSIX notation for character classes, which uses names enclosed by [: and :] within the enclosing square brackets. PCRE supports this notation. For example,

       [01[:alpha:]%]

matches "0", "1", any alphabetic character, or "%". The supported class names are:

  alnum    letters and digits

  alpha    letters

  ascii    character codes 0 - 127

  cntrl    control characters

  digit    decimal digits (same as \d)

  graph    printing characters, excluding space

  lower    lower case letters

  print    printing characters, including space

  punct    printing characters, excluding letters and digits

  space    white space (same as \s)

  upper    upper case letters

  word     "word" characters (same as \w)

  xdigit   hexadecimal digits

The names "ascii" and "word" are Perl extensions. Another Perl extension is negation, which is indicated by a ^ character after the colon. For example,

  [12[:^digit:]]

matches "1", "2", or any non-digit. PCRE (and Perl) also recogize the POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not supported, and an error is given if they are encountered.

Vertical bar

Vertical bar characters are used to separate alternative patterns. For example, the pattern

  gilbert|sullivan

matches either "gilbert" or "sullivan". Any number of alternatives may appear, and an empty alternative is permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the rest of the main pattern as well as the alternative in the subpattern.

Subpatterns

Subpatterns are delimited by parentheses (round brackets), which can be nested. Marking part of a pattern as a subpattern does two things:

1. It localizes a set of alternatives. For example, the pattern

  cat(aract|erpillar|)

matches one of the words "cat", "cataract", or "caterpillar". Without the parentheses, it would match "cataract", "erpillar" or the empty string.

2. It sets up the subpattern as a capturing subpattern (as defined above). When the whole pattern matches, that portion of the subject string that matched the subpattern is passed back to the caller via the ovector argument of pcre_exec(). Opening parentheses are counted from left to right (starting from 1) to obtain the numbers of the capturing subpatterns.

For example, if the string "the red king" is matched against the pattern

  the ((red|white) (king|queen))

the captured substrings are "red king", "red", and "king", and are numbered 1, 2, and 3.

The fact that plain parentheses fulfil two functions is not always helpful. There are often times when a grouping subpattern is required without a capturing requirement. If an opening parenthesis is followed by "?:", the subpattern does not do any capturing, and is not counted when computing the number of any subsequent capturing subpatterns. For example, if the string "the white queen" is matched against the pattern

  the ((?:red|white) (king|queen))

the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of captured substrings is 99, and the maximum number of all subpatterns, both capturing and non-capturing, is 200.

As a convenient shorthand, if any option settings are required at the start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns

  (?i:saturday|sunday)

  (?:(?i)saturday|sunday)

match exactly the same set of strings. Because alternative branches are tried from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday".

Repetition

Repetition is specified by quantifiers, which can follow any of the following items:

  a single character, possibly escaped

  the . metacharacter

  a character class

  a back reference (see next section)

  a parenthesized subpattern (unless it is  an  assertion - see below)

 The general repetition quantifier specifies a minimum and maximum number of permitted matches, by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example:

  z{2,4}

 matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special character. If the second number is omitted, but the comma is present, there is no upper limit; if the second number and the comma are both omitted, the quantifier specifies an exact number of required matches. Thus

  [aeiou]{3,}

 matches at least 3 successive vowels, but may match many more, while

  \d{8}

matches exactly 8 digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters.

The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present.

For convenience (and historical compatibility) the three most common quantifiers have single-character abbreviations:

  *    is equivalent to {0,}

  +    is equivalent to {1,}

  ?    is equivalent to {0,1}

It is possible to construct infinite loops by following a subpattern that can match no characters with a quantifier that has no upper limit, for example:

  (a?)*

Earlier versions of Perl and PCRE used to give an error at compile time for such patterns. However, because there are cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern does in fact match no characters, the loop is forcibly broken.

By default, the quantifiers are "greedy", that is, they match as much as possible (up to the maximum number of permitted times), without causing the rest of the pattern to fail. The classic example of where this gives problems is in trying to match comments in C programs. These appear between the sequences /* and */ and within the sequence, individual * and / characters may appear. An attempt to match C comments by applying the pattern

  /\*.*\*/

to the string

  /* first command */  not comment  /* second comment */

fails, because it matches the entire string due to the greediness of the .* item.

However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead matches the minimum number of times possible, so the pattern

  /\*.*?\*/

 does the right thing with the C comments. The meaning of the various quantifiers is not otherwise changed, just the preferred number of matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because it has two uses, it can sometimes appear doubled, as in

  \d??\d

which matches one digit by preference, but can match two if that is the only way the rest of the pattern matches.

If the PCRE_UNGREEDY option is set (an option which is not available in Perl) then the quantifiers are not greedy by default, but individual ones can be made greedy by following them with a question mark. In other words, it inverts the default behaviour.

When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or with a limited maximum, more store is required for the compiled pattern, in proportion to the size of the minimum or maximum.

If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent to Perl's /s) is set, thus allowing the . to match newlines, then the pattern is implicitly anchored, because whatever follows will be tried against every character position in the subject string, so there is no point in retrying the overall match at any position after the first. PCRE treats such a pattern as though it were preceded by \A. In cases where it is known that the subject string contains no newlines, it is worth setting PCRE_DOTALL when the pattern begins with .* in order to obtain this optimization, or alternatively using ^ to indicate anchoring explicitly.

When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after

  (tweedle[dume]{3}\s*)+

has matched "tweedledum tweedledee" the value of the captured substring is "tweedledee". However, if there are nested capturing subpatterns, the corresponding captured values may have been set in previous iterations. For example, after

  /(a|(b))+/

 matches "aba" the value of the second captured substring is "b".

More ...

There is more than this to regular expressions, however this is the basic part. See the documentation referred to at the start for more details.

Author

  Philip Hazel <ph10@cam.ac.uk>

  University Computing Service,

  New Museums Site,

  Cambridge CB2 3QG, England.

  Copyright (c) 1997-2000 University of Cambridge.

See Also ...

Topics

 Aliases

 Lua LPEG library

 Lua string functions

 Triggers

Dialogs

 Problem parsing regular expression

 Recall

(Help topic: general=regexp)


Scripting

Scripting lets you extend the behaviour of MUSHclient to do almost anything you want.

You can script in one of (currently) eight script languages: VBscript, JScript, PerlScript, Tcl, Python, Lua, TCL and PHPscript. If you use plugins you can also have multiple script languages per session (a different one per plugin).

We recommend using Lua as the preferred scripting language nowadays. Lua ships with MUSHclient, so scripts written in Lua will be more easily exchanged with other MUSHclient users. Also Lua can be used if running under Wine on Linux PCs. The Lua script DLL is shipped with MUSHclient. With the exception of Lua, VBscript and JScript, you will need to download and install the other script engines before using scripts written in those languages.

How do scripts get called?

MUSHclient will call a function (or subroutine) in your script at various places you can specify. For instance, each trigger, timer or alias can call a script. Information about the trigger, alias and timer (such as its name, and the matching line) is passed to the script routine so it can react appropriately.

For example, you might make a trigger script that kept count of the number of times you levelled when playing a MUD.

You can also specify that scripts get called when other events happen, like "world open", "world connect", "new chat user" and so on.

How do scripts communicate with MUSHclient?

Scripts use the COM (Component Object Model) technology to send requests to MUSHclient or ask for information (except for Lua, see below). For example, you can use "Note" to tell MUSHclient to put a note in the output window, or "GetInfo" to find out information about the current world (like when it was connected).

Scripts use the "world" COM object to do this - this is available in all script languages. For example:

world.Note "Hello, there"

Lua scripting

Lua scripting does not use COM, and can thus be used in situations (like running under Wine on Linux) where COM is not working reliably.

Lua scripts are called directly from MUSHclient, generally with the same arguments as the COM scripts. There are some minor exceptions, these are noted under the relevant entries for each script function.

Where do scripts go?

You have a number of options for placing script routines -

1. In a script file which is used by the world (these can be shared between worlds).

2. Each plugin you install can have scripts in it.

3. Triggers, aliases and timers can call a script functions directly from inside them, without needing a separate script file. This is called "send to script".

Script functions

There is extensive documentation about the script functions, including a list of all of them, at the web page:

http://www.gammon.com.au/mushclient/functions.htm

Lua

Commencing with version 3.52, the Lua language is supported. You can read more about Lua at:

http://www.lua.org/

Unlike the other languages, support for Lua is "hard-coded" into MUSHclient, it does not use the COM (Component Object Model) interface. This allows Lua to be supported in a consistent way, even on platforms that do not support other languages (eg. Linux).

Forum posting about scripting

There is a lengthy post on the MUSHclient forum about using scripting, see this:

http://www.gammon.com.au/forum/?id=6030

Functions ...

Scripting functions list

See Also ...

Topics

 Arrays

 Database (SQLite)

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Plugins

 Scripting callbacks - MXP

 Scripting callbacks - plugins

 Scripting data types

 Scripting functions list

 Scripting return codes

 Utilities

 Variables

 World functions

Commands

 ConfigureScripting (Sets scripting options)

 EditScriptFile (Edits the current script file)

 Immediate (Allows testing of scripts)

 ReloadScriptFile (Forces script source file to be reprocessed)

 SendToScript (Sends the selection to the script engine of the related world)

Dialogs

 Debug

 Global preferences - Lua

 Immediate

 Missing script procedure names

 MXP script routines

 Scripting Error

 Scripts

(Help topic: general=scripting)


Scripting callbacks - MXP

When using MXP you can have various events call a script in your script file. This lets you customise your handling of things like errors, variables being set, and so on.

To add these script handlers, go to the Configuration screen -> Scripts and click on the "MXP" button.

Then fill in the names of the routines you wish to call. The actual names do not matter, as long as they agree with the names used in your script file.

Some example scripts are shown below, these also illustrate the correct argument lists for each function.

Plugins

You can also call these routines inside plugins. In this case they must have fixed names, as there is no way of configuring the names to be used. Each item indicates the appropriate name to be used in a plugin.

MXP startup

This is called when MXP is started.

Inside a plugin: OnPluginMXPstart

function OnMXPStart ()

  Note "MXP started."

end -- function

MXP shutdown

This is called when MXP is stopped.

Inside a plugin: OnPluginMXPstop

function OnMXPShutdown ()

  Note "MXP stopped."

end -- function

MXP errors

This routine is called whenever an error, warning or information message is generated by MXP. This routine is called regardless of the "MXP debug" level you have set in your configuration screen. This lets you handle MXP errors in your own way. For instance, set the "MXP debug" level to "none" and display selected message to the output window or a notepad window.

Note: Lua exception

For Lua scripts, the arguments are passed in a different order than described below, namely:

 •	Error number

 •	Line number

 •	Error level

 •	Error message

For example:

function OnMXPError (number, line, level, message)

  -- processing here

end -- function

Inside a plugin: OnPluginMXPerror

The first argument is the "level" of the message, namely:

  •	"E" - error

  •	"W" - warning

  •	"I" - information

  •	"A" - all other messages

You might choose to only display "E" messages.

The second argument is the message number. This is a different number for each message, so you could choose to filter in (or out) particular message numbers. See the next posting for a list of message numbers.

The third argument is the line number of the current line in the output buffer (actually the count of lines in the output buffer). Effectively this identifies the line which caused the error, although in a sense the line is only a "nearby" line as MXP tags do not necessarily in themselves cause output to be sent to the output window.

Also, if the output buffer fills up, and lines at the top are discarded, then the line number will eventually become incorrect.

For example, if you have an error in line 1, the output buffer is 5,000 lines long, and you have received 10,000 lines, then clearly line 1 in the output buffer is not the same line 1 that reported the error. If you are trying to debug MXP problems you are advised to set your output buffer size to some large figure (eg. 100,000 lines) so that this problem does not arise quickly.

The fourth argument is the message text itself, which is usually pretty self-explanatory, and includes the name of the tag or item in error.

function OnMXPerror (level, number, line, message)

  if level == "E" and number ~= 1030 then

    ColourNote ("white", "red", level .. "(" .. number .. "): " message)

  end if

-- do not display entities received (eg. &lt; )

  if number == 20001 then

     return 1

  end -- if

  return 0

end -- function

If you want to fine-tune which errors are shown in the standard MXP message window, you can return a non-zero value for any messages that are to be suppressed.

The example above returns 1 to suppress message 20001 from appearing in the message window. (This only applies in the main script file, not plugins).

MXP start tag

This routine is called when a "start" tag is parsed (successfully). For example, "<send href='go west'>".

Inside a plugin: OnPluginMXPopenTag

Some tags, marked as EMPTY, do not have end tags, and thus you would need to detect them here, rather than looking for their end tag.

The arguments are:

1. Tag name, eg. "send". The name will always be in lower case.

2. Arguments as provided, eg. "href='go west'"

3. Arguments parsed into a list. There will be one entry in the list for each argument. They will be supplied in the format "name=value", eg. "href=go west". If there were quotes around the argument value they will be removed. Thus, to find the name and the value, everything before the first "=" is the argument name, everything after the first "=" is the argument value.

Arguments without a name will be named by an ascending number, eg. "1=prompt" means "prompt" is the first un-named argument.

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:

 •	tagname,arguments ... eg: sound,volume=1 pan=2 name="boing.wav"

You are advised to not use world.Note to display the tag name/arguments to the output window, because this is likely to interfere with the MXP routines which are trying to work out, for example, which words to underline. You are best sending any debug information to another window, as in the example below.

function OnMXPStartTag (name, args, mylist)

  AppendToNotepad ("MXP", "Opening tag: " .. name .. "\n")

  AppendToNotepad ("MXP", "Argument list: "  .. args .. "\n")

  if mylist then

    for k, v in pairs (mylist) do

      AppendToNotepad ("MXP", "Arg " .. k .. " = " + v .. "\n")

    end -- for

  end -- if

  -- suppress color tags

  if name == "color" then

    return 1

  end -- if

end -- function

If you want to suppress certain tags, you can return a non-zero value for the corresponding tag name, as in the example above.

MXP end tag

This routine is called when an "end" tag is parsed (successfully). For example, "</send>".

Inside a plugin: OnPluginMXPcloseTag

Some tags, marked as EMPTY, do not have end tags.

The arguments are:

1. Tag name, eg. "send"

2. Value of "&text;" variable. In other words, everything that appeared between the start tag and the end tag. This is limited to 1000 characters maximum.

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:

 •	tagname,text ... eg: send,eat newspaper

For example, if you had:

<send>eat newspaper</send>

The value of &text; would be "eat newspaper".

function OnMXPEndTag (name, text)

  AppendToNotepad ("MXP", "Closing tag: " .. name .. "\n")

  AppendToNotepad ("MXP", "Text: " .. text .. "\n")

end -- function

MXP set variable

This is called when MXP sets a MUSHclient variable (by using the FLAG parameter on an element definition).

Inside a plugin: OnPluginMXPsetVariable

MXP variables are prefixed by "mxp_" so that they do not clash with variable names that you might already be using in your scripts.

The arguments are:

1. Variable name, eg. "mxp_hp"

2. Value of variable, eg. "22"

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:

 •	variable, value  ... eg: max_hp,22

function OnMXPvariable (name, contents)

  Note ("Var " .. name .. " set to " .. contents)

end -- function

Setting an MXP entity (plugins only)

Inside a plugin you can detect an entity being changed by the MXP code from the MUD (not using the script SetEntity function).

Inside a plugin: OnPluginMXPsetEntity

The argument is: entityname=newvalue

function OnPluginMXPsetEntity (value)

  Note (value)  -- eg. foo=bar

end -- function

See Also ...

Topic

 Scripting

(Help topic: general=mxp_callbacks)


Scripting callbacks - plugins

The following subroutines/functions will be called in your plugin if they are present. The names are hard-coded, and a check is made to see if such names exist when the plugin is installed. As each one starts with the characters "OnPlugin" you should not get clashes with your own routines, provided you avoid using that particular prefix when naming your own functions. The example code below is in Lua.

OnPluginInstall

--

-- Plugin has been installed (added).

-- This is done immediately after the plugin has been added to the world's

-- list of plugins, and all plugin callback entry points found.

-- Note that any script instructions *outside* a plugin function will be

-- executed *before* this (as part of loading the script space).

--

function OnPluginInstall ()

end -- function

OnPluginListChanged

--

-- The list of plugins has changed

-- This includes: adding, removing, enabling, disabling a plugin

-- It also includes scripted loading and reloading of a plugin.

-- It is also called when loading a world file, after all plugins are loaded.

--

function OnPluginListChanged ()

end -- function

OnPluginClose

--

-- Plugin is being removed (closed).

-- Note that all plugins are closed when the world file is closed.

--

function OnPluginClose ()

end -- function

OnPluginConnect

--

-- This world has been connected (to the MUD).

-- This is done after the username and password have been sent (if any).

-- It is done after the NAWS telnet negotiation, if any. (IAC, WILL, TELOPT_NAWS)

-- It is done after the main world's "connect" function, if any.

-- It is done after the log file is opened, if one is being opened automatically.

--

function OnPluginConnect ()

end -- function

OnPluginDisconnect

--

-- This world has been disconnected (from the MUD).

-- This is called after the main world's "disconnect" function, if any.

-- It is called before the log file is closed, if any.

--

function OnPluginDisconnect ()

end -- function

OnPluginSaveState

--

-- The plugin is about to save its state

-- If you want to create new variables to be saved (eg. save script variables as MUSHclient variables)

--  now is the time to do it.

--

function OnPluginSaveState ()

end -- function

OnPluginWorldSave

--

-- The main world file is being saved.

-- If you want to save things (eg. to a database or separate file) when the

-- world file is being saved do it now).

--

function OnPluginWorldSave ()

end -- function

OnPluginEnable

--

-- The plugin is being enabled.

-- This is done *after* the enable flag is turned on.

--

function OnPluginEnable ()

end -- function

OnPluginDisable

--

-- The plugin is being disabled.

-- This is done *after* the enable flag is turned off.

--

function OnPluginDisable ()

end -- function

OnPluginGetFocus

--

-- The world to which the plugin belongs is getting the focus

--

function OnPluginGetFocus ()

end -- function

OnPluginLoseFocus

--

-- The world to which the plugin belongs is losing the focus

--

function OnPluginLoseFocus ()

end -- function

OnPluginCommand

--

--  The player has typed the command 'sText'

--  Return TRUE to process the command, FALSE to discard it

--

function OnPluginCommand (sText)

  return true -- process it

end -- function

OnPluginCommandChanged

--

--  The contents of the command window has changed.

--

function OnPluginCommandChanged ()

  -- check contents of command window (eg. spellcheck)

end -- function

OnPluginCommandEntered

--

-- The player has typed the command 'sText' and pressed <Enter>

--

-- You can modify the command in this function, and return the modified string

--   which is what will be sent to the command processor.

-- If you return an empty string, that will sent to the command processor.

-- If you return a tab character on its own (\t or hex 09) then the command will be

-- discarded, and the command window cleared (unless auto-repeat commands is set).

--

-- If you return a carriage-return character on its own (\r or hex 0D) then the command will be

-- discarded, and retained in the command window.

--

-- This differs from OnPluginCommand which processes individual command lines,

--  after command stacking and other processing has taken place.

--

--  The example replaces line breaks by %r.

--

--  You might use this to implement your own "rules" for evaluating command stacking,

--  spell checking, keeping a command history, and so on.

--

function OnPluginCommandEntered (sText)

  return string.gsub (sText, "\n", "%r")

end -- function

OnPluginTabComplete

--

-- The player has typed some text into the command window and pressed <Tab>.

--

-- The tab completion processing has found a match.

--

-- You can modify the match text in this function, and return the modified string

--   which is what will be replaced into the command window.

function OnPluginTabComplete (s)

  utils.msgbox (s)

end -- function

OnPluginSend

--

--  MUSHclient is proposing to send 'sText' to the MUD

--  Return TRUE to send the text, FALSE to discard it

--

-- If any plugin returns FALSE, then the text is not actually sent.

--

-- If you want to know what was actually sent, use OnPluginSent (below).

--

--  If you call world.Send from within this function, OnPluginSend is not called again (however OnPluginSent will be).

--

function OnPluginSend (sText)

  return true  -- process it

end -- function

OnPluginSent

--

--  MUSHclient is definitely sending 'sText' to the MUD

--

-- This is called after every plugin has a chance to reject the text in the

--   OnPluginSend callback.

--

--  An example of use of this would be for an auto-mapper, as this function gets

--   text that has definitely been sent to the MUD.

--

-- If you call world.Send from within this callback, it will return an error.

--

--  OnPluginSent is supposed to be recording what is being sent, not sending new things.

--

function OnPluginSent (sText)

end -- function

OnPluginLineReceived

--

--  MUSHclient has received the line 'sText'

--  Return TRUE to process the text, FALSE to discard it

--

function OnPluginLineReceived (sText)

  return true  -- display it

end -- function

In the case of routines like OnPluginCommand (about to send a command to the MUD), each plugin is scanned for every command entered. If any plugin returns FALSE, then that command is not processed. This gives each plugin a chance to respond to various commands, and suppress them if it wants to. Likewise for OnPluginSend (attempting to send a line of text to the MUD) and OnPluginLineReceived (received a line of text from the MUD).

OnPluginPacketReceived

--

--  MUSHclient has received the packet 'sText'

--

function OnPluginPacketReceived (sText)

end -- function

This function is called when each incoming packet (data) arrives from the MUD. A packet does not necessarily start or end on line boundaries, and may consist of partial text lines, or more than one line. If compression (MCCP) is active, the packet is the data after decompression.

Be warned that when compression is turned on, one packet may contain both uncompressed and compressed data (with the "turn on compression" sequence between them). Changing data in that packet may cause decompression to fail, if you alter the compressed part of the packet.

You can return data from this function (in version 3.59 onwards). If you do, then the returned data will replace the incoming data. In other words, you can change words, omit lines, add new lines, and MUSHclient will proceed as if the altered line had arrived from the MUD.

OnPluginPartialLine

This will be called when one of these events occurs:

•	 A line fills up (eg. you hit 80 characters if that is your screen width)

•	 A newline is received

•	 A partial packet is received, and no more input is currently available

The plugin is passed the current line - not just the new text - (which may or may not be "full" if the third condition is met) - which it can then test or pass into a regular expression for more complex testing.

This is intended to catch those situations where you need an immediate update (eg. a prompt line, entering a username/password when the newline is not present) on data received from the MUD.

Note that triggers will still be evaluated in the usual way, at the usual time. The plugin callback just gives you the chance to get at it sooner.

function OnPluginPartialLine (sText)

  AppendToNotepad ("test", sText . "\r\n")

end -- function

OnPluginBroadcast

When a script calls BroadcastPlugin then all installed plugins are checked for a function OnPluginBroadcast. If present, it is called with 4 arguments:

•	The message number (the first argument to BroadcastPlugin).

•	The ID of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

•	The name of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

•	The Text argument (the second argument to BroadcastPlugin)

An example of a plugin handler might be (in Lua):

function OnPluginBroadcast (msg, id, name, text)

  Note ("msg = " .. msg)

  Note ("id = " .. id)

  Note ("name = " .. name)

  Note ("text = " .. text)

end

The calling plugin ID and name are supplied so that plugin writers can verify which plugin originated a particular message. This cannot be spoofed as it is supplied automatically by MUSHclient.

OnPluginTrace

This is called when you have tracing turned on. If a plugin is found with this function in it, then it is called and the trace line is not displayed on the world output window. Only the first plugin found is called.

Example, in Lua:

function OnPluginTrace (line)

  AppendToNotepad ("Trace", line .. "\r\n")

end

OnPluginScreendraw

This is intended for people with screen readers, who want the contents of the main window read out, however don't want gagged text to be read. The current way MUSHclient works is to draw text as it arrives, and then "undraw it" if it is gagged. This approach doesn't really work with screen readers, as they can't "unread" something.

The arguments to OnPluginScreendraw are:

Type: type of line, where 0 = output line, 1 = note, 2 = command

Log: are we planning to log it?

Line: the text of the line itself

An example plugin function, which simply copies the text to a notepad window, is as follows:

function OnPluginScreendraw (type, log, line)

  AppendToNotepad ("mylog", type, " ", log, " ", line, "\r\n")

end -- function

OnPluginDrawOutputWindow

This is intended to allow plugin writers to make a miniwindow that has text that scrolls with the output window. It is called at the start of drawing (refreshing) the output window (eg. when a new line arrives from the MUD, or after a Note).

The arguments to OnPluginDrawOutputWindow are:

FirstLine: The first line number which is going to be drawn (starting at 1). You can use GetLineInfo to get details about that line.

ScrollOffset: The pixel position which it will start drawing at (based on the scroll bar thumb position). You can use that to tweak which pixel to start drawing at vertically.

NotUsed: An empty string (required because of the way plugin callbacks are implemented).

Example of echoing the line number in the output buffer, plus the text of the line is:

function OnPluginDrawOutputWindow (firstline, offset, notused)

  local background_colour = ColourNameToRGB ("lightgray")

  local text_colour = ColourNameToRGB ("green")

  local main_height = GetInfo (263)

  local font_height = GetInfo (212)

  -- clear window

  WindowRectOp (win, miniwin.rect_fill, 0, 0, 0, 0, background_colour)

  -- allow for scrolling position

  local top =  (((firstline - 1) * font_height) - offset) - 2

  -- how many lines to draw

  local lastline = firstline + (main_height / font_height)

  for line = firstline, lastline do

    if line >= 1 and GetLineInfo (line, 1) then

      WindowText (win, font, line .. ": " .. GetLineInfo (line, 1), 0, top,

                  0, 0, text_colour)

      top = top + font_height

    end -- if line exists

  end -- for each line

end -- OnPluginDrawOutputWindow

Do not call WindowCreate inside this callback or strange things may happen as it is in the middle of drawing to the output device context. Reserve creating the window for OnPluginInstall and OnPluginWorldOutputResized.

Do not call Repaint inside this callback or the client will go into an infinite loop (it is already repainting the window, so trying to repaint it while repainting it will cause a loop). Also do not do things like print to the output window (eg. using Note) as that will cause the output window to be redrawn, and then the callback will be called again, and so on.

OnPluginPlaySound

This is called when MUSHclient intends to play a sound (eg. new activity sound, trigger sound, world.Sound script function). If it finds a plugin with the OnPluginPlaySound function defined, then that is called, and the internal sound-player is not used. The only argument is the sound file name that is to be played.

function OnPluginPlaySound (sound)

  Note ("Playing sound ", sound)

end -- function

If you select the Display > Stop Sound Playing menu item, then OnPluginPlaySound will be called with an empty file name.

 OnPluginWorldOutputResized

This is called when the output window is resized.

function OnPluginWorldOutputResized ()

  -- do something here

end -- function

 OnPluginMouseMoved

This is called when the mouse is moved inside the output window.

function OnPluginMouseMoved (x, y, mw)

  -- do something here

  return 0

end -- function OnPluginMouseMoved

The x and y arguments (long integers) give the location of the mouse, relative to the top-left corner of the current world's output window.

The third argument is the miniwindow ID of any miniwindow the mouse may happen to be over, or "" if it is not over a miniwindow.

 OnPluginTick

This is called 25 times a second.

function OnPluginTick ()

  -- do something here

  return 0

end -- function OnPluginTick

This is called 25 times a second (every 40 milliseconds), even if timers are disabled.

It is intended as a simple way of doing things that need to be done smoothly and more rapidly than timers allow (timer granularity is set to a minimum of 1/10 of a second). For example, when using the sound functions such as PlaySound, you could smoothly fade music up or down using this callback.

Also you might use it to implement scrolling text (eg. a miniwindow that says "Critical Hit!") which smoothly scrolls up the screen and disappears. The callback is called 25 times a second as 25 fps (frames per second) is about the minimum for smooth animation, so animated effects (like scrolling text) should look reasonably smooth if implemented using this.

Warning! This is implemented using a Windows timer event (WM_TIMER). This is a low-priority event, which means it may not be called if other things are happening. In other words, the timer may fire less frequently than 25 times a second, depending on what else is happening.

OnPluginTelnetRequest

This is called if the server sends IAC WILL x, or IAC DO x to the client. In that case the callback lets you decide whether or not to handle the protocol (eg. ATCP or ZMP). The following protocols are handled internally and may not cause a call to this function (in some cases for DO and in some cases for WILL):

  1 (ECHO)     - output echo on/off

  3 (SGA)      - Suppress Go Ahead

 24 (TERMTYPE) - send terminal type

 25 (EOR)      - End Of Record

 31 (NAWS)     - Negotiate About Window Size

 70 (MSSP)     - MUD Server Status Protocol

 85 (MCCP v1)  - MUD Client Compression Protocol version 1

 86 (MCCP v2)  - MUD Client Compression Protocol version 2

 91 (MXP)      - MUD eXtension Protocol

102 (Aardwolf options)  - used by Aardwolf MUD and some MUSHclient plugins

If you return true then MUSHclient will send a positive response to the server and then call OnPluginTelnetRequest a second time with another code, as follows:

If it initially called the plugin with "WILL" it will call back with "SENT_DO".

If it initially called the plugin with "DO" it will call back with "SENT_WILL".

This is because the positive response to WILL is DO, and the positive response to DO is WILL. This second call to OnPluginTelnetRequest lets you do extra processing after agreeing to the negotiation with the server, such as logging on to it.

The OnPluginTelnetRequest function should return true to indicate it handled the message, or false if it did not. Once OnPluginTelnetRequest returns true in one plugin, no further plugins are checked. This is to stop multiple plugins logging in, as presumably a single login is all that is required.

function OnPluginTelnetRequest (type, data)

  if type == 200 and data == "WILL" then

    return true

  elseif type == 200 and data == "SENT_DO" then

    -- IAC SB 200 response IAC SE

    SendPkt ("255250200Server.Logon Nick255240")  -- example only

  end -- if

end -- function OnPluginTelnetRequest

OnPluginTelnetSubnegotiation

This is called if the server sends IAC SB x <data> IAC SE to the client. In that case the callback lets you handle the protocol yourself. The following types are not sent as they are handled internally.

24 (terminal type)

42 (charset)

85 (MCCP v1)

86 (MCCP v2)

91 (MXP)

In the case of type 102, then OnPluginTelnetOption is called as well (without the option number, as that is fixed at 102).

function OnPluginTelnetSubnegotiation (type, data)

  Note ("received negotiation: ", telnet_option)

  Note ("Received option string ", utils.tohex (data))

end -- function OnPluginTelnetSubnegotiation

Note - despite the above example, it is not recommended that you do Notes (or anything similar) when receiving telnet subnegotiation packets. Doing a Note may switch the current line from "MUD output" to "Note line" in ways that are not expected, particularly if you are hoping to trigger on the next line that arrives.

OnPluginTelnetOption

This is called if the server sends IAC SB 102 <data> IAC SE to the client. In that case the callback lets you handle the protocol yourself. This is similar to OnPluginTelnetSubnegotiation but is included separately for backwards compatibility. Note that OnPluginTelnetSubnegotiation is also called (afterwards), so new scripts can just use OnPluginTelnetSubnegotiation.

function OnPluginTelnetOption (data)

  Note ("Received option string ", utils.tohex (data))

end -- function OnPluginTelnetOption

OnPlugin_IAC_GA

This is called if the server sends IAC GA (0xFF 0xF9) or IAC EOR (0xFF 0xEF) to the client. This is intended for situations like where the ATCP protocol sends a whole lot of telnet negotiation sequences, and then IAC GA when waiting for player input. In this case the IAC GA could be a signal to a plugin to start responding.

function OnPlugin_IAC_GA ()

  -- respond to server

end -- function OnPlugin_IAC_GA

Chat System Callbacks

OnPluginChatAccept

--  MUSHclient has received a connection from IP,name

--  Return TRUE to accept it, FALSE to reject it

--

function OnPluginChatAccept (sText)

local username, ip = string.match (sText, "(.-),(.+)")

end -- function

OnPluginChatMessage

--  MUSHclient has received chat message: id, message, text

--  Return TRUE to use the default processing, FALSE to ignore it

--

--  The message code indicating the chat message, where these are likely

--         to be received:

--

--   1    Name_change

--   2    Request_connections

--   3    Connection_list

--   4    Text_everybody

--   5    Text_personal

--   6    Text_group

--   7    Message

--   8    Do_not_disturb

--   9    Send_action

--  10    Send_alias

--  11    Send_macro

--  12    Send_variable

--  13    Send_event

--  14    Send_gag

--  15    Send_highlight

--  16    Send_list

--  17    Send_array

--  18    Send_baritem

--  19    Version

--  20    File_start

--  21    File_deny

--  22    File_block_request

--  23    File_block

--  24    File_end

--  25    File_cancel

--  26    Ping_request

--  27    Ping_response

--  28    Peek_connections

--  29    Peek_list

--  30    Snoop

--  31    Snoop_data

-- 105    Send_command

function OnPluginChatMessage (id, message, sText)

  return true -- process it

end -- function

OnPluginChatMessageOut

--  MUSHclient is about to send chat message: id, message, text

--  Return TRUE to use the default processing, FALSE to ignore it

--

--  See above for the exact message numbers that might be sent.

function OnPluginChatMessageOut (id, message, sText)

  return true -- process it

end -- function

OnPluginChatDisplay

--

--  MUSHclient is about to display message: message, text

--  Return TRUE to use the default display, FALSE to not display

--

--  See above for the exact message types that might be received.

--

function OnPluginChatDisplay (message, sText)

  return true -- display it

end -- function

OnPluginChatNewUser

--

-- A new chat user has been accepted on: id, name

--

--

-- This script callback has been provided so you can take action if

-- you want (such as allowing file transfers).

--

function OnPluginChatNewUser (id, name)

end -- function

OnPluginChatUserDisconnect

-- This chat user has disconnected for one reason or another.

--

-- This callback lets you take action (eg. notify others) however

-- you cannot send messages to this connection or change any options

-- once they have disconnected. The chat id is supplied so you can

-- match the id to the one that connected.

--

-- For each call to OnPluginChatNewUser there should eventually be a

-- corresponding call to OnPluginChatUserDisconnect.

--

function OnPluginChatUserDisconnect (id, name)

end -- function

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

(Help topic: general=plugin_callbacks)


Scripting data types

Below are the types of data you can supply to script routines (as shown in the "prototypes" for each script function).

BOOL

True or False.

Lua type: boolean

boolean

True or False.

Lua type: boolean

BSTR

A character string (eg. "swordfish").

Lua type: string

Strings are stored as "null-terminated". That is, a byte with the value 0 (null) indicates the end of a string. Thus, strings may not contain imbedded null characters.

IDispatch

An object reference.

Lua type: not supported

long

A 32-bit number (from -2147483647 to +2147483647).

Lua type: number

short

A 16-bit number (from -32768 to +32767).

Lua type: number

date

A date/time field.

Lua type: number

VARIANT

A Visual-Basic "variant" data type, which can hold different types of data. A variant can be "null", "empty", or contain a number, character string, or an array, amongst other things. You can use the Visual Basic "VarType" function to find exactly what sort of data is in a variant.

Lua type: any (all variables in Lua can be any type)

void

No return value.

Lua type: nil

The safest way to test for "true" or "false" is to assume that zero (0) is false, and any other value is true.

Similarly, to supply the value "true" simply supply a 1, and to supply the value "false", supply the value 0.

See also ...

Script information

Scripting functions list

Scripting return codes list

See Also ...

Topic

 Scripting

(Help topic: general=data_types)


Scripting functions list

Below is a list of each script function in the current version of MUSHclient. Click on any link for more information about that function.

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

 Activate (Activates the world window)

 ActivateClient (Activates the main MUSHclient window)

 ActivateNotepad (Activates a notepad window)

 AddAlias (Adds an alias)

 AddFont (Adds a custom font for use by MUSHclient)

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 AddTimer (Adds a timer)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 AppendToNotepad (Appends text to a notepad window)

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

 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)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 Bookmark (Sets of clears a bookmark on the nominated line)

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 ChangeDir (Changes the MUSHclient working directory)

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 CloseLog (Closes the log file)

 CloseNotepad (Closes a notepad window)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 Connect (Connects the world to the MUD server)

 CreateGUID (Creates a GUID - Global Unique Identifier)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

 Debug (Displays debugging information about the world)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteCommandHistory (Deletes command history list.)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 DeleteLines (Clears some recent lines from the output window.)

 DeleteOutput (Clears all output from the output window.)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 DeleteVariable (Deletes a variable)

 DiscardQueue (Discards the speed walk queue)

 Disconnect (Disconnects the world from the MUD server)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 DoCommand (Queues a MUSHclient menu command)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 EditDistance (Returns the Levenshtein Edit Distance between two words)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableMapping (Enables or disables the auto-mapper)

 EnablePlugin (Enables or disables the specified plugin)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 ErrorDesc (Converts a MUSHclient script error code into an human-readable description)

 EvaluateSpeedwalk (Evaluates a speed walk string)

 Execute (Executes a command as if you had typed it into the command window)

 ExportXML (Exports a world item in XML format)

 FilterPixel (Performs a filtering operation on one pixel)

 FixupEscapeSequences (Converts "escape sequences" like &#x5C;t to their equivalent codes.)

 FixupHTML (Fixes up text for writing as HTML)

 FlashIcon (Flashes the MUSHclient icon on the Windows taskbar)

 FlushLog (Flushes the log file to disk)

 GenerateName (Generates a random character name)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 GetClipboard (Gets the clipboard contents)

 GetCommand (Gets the current command in the command window)

 GetCommandList (Returns some or all commands from the command history)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetCurrentValue (Gets the current value of a named world option)

 GetCustomColourName (Gets the name of a custom colour)

 GetDefaultValue (Gets the default value of a named world option)

 GetDeviceCaps (Gets screen device capabilities)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetFrame (Returns the address of the main MUSHclient frame window)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetNoteStyle (Gets the style for notes)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetScriptTime (Returns the amount of time spent in script routines)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetSoundStatus (Gets the status of a sound started by PlaySound)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 GetUdpPort (Find a free port for UDP listening)

 GetUniqueID (Creates a unique ID for general use, or for making Plugin IDs)

 GetUniqueNumber (Returns a unique number)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 Hyperlink (Creates a hyperlink in the output window)

 ImportXML (Imports configuration data in XML format)

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 IsAlias (Tests to see if an alias exists)

 IsConnected (Tests to see if the world is connected to the MUD server)

 IsLogOpen (Tests to see if a log file is open)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 IsTimer (Tests to see if a timer exists)

 IsTrigger (Tests to see if a trigger exists)

 LoadPlugin (Loads a plugin from disk)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 MakeRegularExpression (Converts wildcard matching text to a regular expression)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 Mapping (A flag to indicate whether we are mapping the world)

 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)

 MoveNotepadWindow (Move and resize the specified notepad 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)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteHr (Draws a horizontal rule in the output window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 NoteStyle (Sets the style for notes)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

 OpenLog (Opens a log file.)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Pause (Turns pause mode on or off)

 PickColour (Invokes the MUSHclient colour picker dialog)

 PlaySound (Plays a sound using DirectSound)

 PluginSupports (Checks if a plugin supports a particular routine)

 PushCommand (Pushes the current command into the command history list)

 Queue (Queues a command for sending at the "speed walk" rate.)

 ReadNamesFile (Loads in a file for generating character names)

 Redraw (Schedules a redraw for all windows for this world)

 ReloadPlugin (Reloads an installed plugin)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

 Repaint (Forces an immediate redraw for all windows for this world)

 Replace (Replaces one substring with another)

 ReplaceNotepad (Replaces text in a notepad window)

 Reset (Resets all outstanding MXP/Pueblo tags)

 ResetIP (Resets the cached IP address of the world and proxy server)

 ResetStatusTime (Resets the time elapsed shown on the status bar)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 ReverseSpeedwalk (Reverses a speed walk string)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 Save (Saves world configuration.)

 SaveNotepad (Saves a notepad window to disk)

 SaveState (Saves the state of the current plugin)

 SelectCommand (Selects (highlights) the current command in the command window)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SendToNotepad (Creates a notepad and sends text to it)

 SetAliasOption (Sets the value of a named alias option)

 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)

 SetChanged (Sets or clears the "document has changed" flag)

 SetChatOption (Sets the value of a chat session option)

 SetClipboard (Sets the clipboard contents)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

 SetCommandWindowHeight (Set the height of the command (input) window)

 SetCursor (Changes the shape of the mouse cursor)

 SetCustomColourName (Sets the name of a custom colour)

 SetEntity (Sets the value of an MXP entity)

 SetForegroundImage (Sets a foreground image for the output window)

 SetInputFont (Sets the font for the input window)

 SetMainTitle (Sets the main output window title)

 SetNotes (Sets the notes for the world.)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

 SetScroll (Sets the scroll bar position, and hides or shows it)

 SetStatus (Sets the status line text)

 SetTimerOption (Sets the value of a named timer option)

 SetTitle (Sets the world window title)

 SetToolBarPosition (Sets the position of the game toolbars on the screen.)

 SetTriggerOption (Sets the value of a named trigger option)

 SetUnseenLines (Sets the number of "unseen lines" for this world)

 SetVariable (Sets the value of a variable)

 SetWorldWindowStatus (Sets the scroll bar position, and hides or shows it)

 ShiftTabCompleteItem (Adds an item to  the list shown for Shift+Tab completion)

 ShowInfoBar (Shows or hides the "info" tool bar)

 Simulate (Simulate input from the MUD, for debugging purposes)

 Sound (Plays a sound)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

 StopEvaluatingTriggers (Stops trigger evaluation)

 StopSound (Stop playing a sound started by PlaySound)

 StripANSI (Strips ANSI colour sequences from a string)

 Tell (Sends a message to the output window - not terminated by a newline)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 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)

 UdpListen (Listens for incoming packets using the UDP protocol)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 UdpSend (Sends a packet over the network using the UDP protocol)

 UnloadPlugin (Unloads an installed plugin)

 Version (Gets the MUSHclient version string.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

 WriteLog (Writes to the log file)

See also ...

Data types

Scripting return codes list

See Also ...

Topics

 Lua script extensions

 Scripting

(Help topic: general=function_list)


Scripting return codes

Below is a list of the error codes that are returned by many script routines. Some scripts return different codes (such as variants), see those functions for more information.

The English meaning (eg. "The world is already open") can also be obtained by calling the ErrorDesc script function. The descriptions corresponding to an error code can also be found in Lua by indexing into the error_desc table (as in the "check" function below).

There is a function built into the Lua script space which will check for errors automatically:

function check (result)

  if result ~= error_code.eOK then

    error (error_desc [result] or

           string.format ("Unknown error code: %i", result),

           2) -- error level - whoever called this function

  end -- if

end -- function check

If you pass an error code to the "check" function it will raise an error if the code is not valid (ie. not zero), with the appropriate error message. For example:

check (WindowShow ("foo", true))   -- raises error if window "foo" does not exist

The error codes can also be accessed from Lua using the error_code table (eg. error_code.eOK, error_code.eCannotPlaySound).

Mnemonic/Value	Meaning
eOK (0)	No error
eWorldOpen (30001)	The world is already open
eWorldClosed (30002)	The world is closed, this action cannot be performed
eNoNameSpecified (30003)	No name has been specified where one is required
eCannotPlaySound (30004)	The sound file could not be played
eTriggerNotFound (30005)	The specified trigger name does not exist
eTriggerAlreadyExists (30006)	Attempt to add a trigger that already exists
eTriggerCannotBeEmpty (30007)	The trigger "match" string cannot be empty
eInvalidObjectLabel (30008)	The name of this object is invalid
eScriptNameNotLocated (30009)	Script name is not in the script file
eAliasNotFound (30010)	The specified alias name does not exist
eAliasAlreadyExists (30011)	Attempt to add a alias that already exists
eAliasCannotBeEmpty (30012)	The alias "match" string cannot be empty
eCouldNotOpenFile (30013)	Unable to open requested file
eLogFileNotOpen (30014)	Log file was not open
eLogFileAlreadyOpen (30015)	Log file was already open
eLogFileBadWrite (30016)	Bad write to log file
eTimerNotFound (30017)	The specified timer name does not exist
eTimerAlreadyExists (30018)	Attempt to add a timer that already exists
eVariableNotFound (30019)	Attempt to delete a variable that does not exist
eCommandNotEmpty (30020)	Attempt to use SetCommand with a non-empty command window
eBadRegularExpression (30021)	Bad regular expression syntax
eTimeInvalid (30022)	Time given to AddTimer is invalid
eBadMapItem (30023)	Direction given to AddToMapper is invalid
eNoMapItems (30024)	No items in mapper
eUnknownOption (30025)	Option name not found
eOptionOutOfRange (30026)	New value for option is out of range
eTriggerSequenceOutOfRange (30027)	Trigger sequence value invalid
eTriggerSendToInvalid (30028)	Where to send trigger text to is invalid
eTriggerLabelNotSpecified (30029)	Trigger label not specified/invalid for 'send to variable'
ePluginFileNotFound (30030)	File name specified for plugin not found
eProblemsLoadingPlugin (30031)	There was a parsing or other problem loading the plugin
ePluginCannotSetOption (30032)	Plugin is not allowed to set this option
ePluginCannotGetOption (30033)	Plugin is not allowed to get this option
eNoSuchPlugin (30034)	Requested plugin is not installed
eNotAPlugin (30035)	Only a plugin can do this
eNoSuchRoutine (30036)	Plugin does not support that subroutine (subroutine not in script)
ePluginCouldNotSaveState (30037)	Plugin could not save state (eg. no state directory)
ePluginDoesNotSaveState (30037)	Plugin does not support saving state
ePluginDisabled (30039)	Plugin is currently disabled
eErrorCallingPluginRoutine (30040)	Could not call plugin routine
eCommandsNestedTooDeeply (30041)	Calls to "Execute" nested too deeply
eCannotCreateChatSocket (30042)	Unable to create socket for chat connection
eCannotLookupDomainName (30043)	Unable to do DNS (domain name) lookup for chat connection
eNoChatConnections (30044)	No chat connections open
eChatPersonNotFound (30045)	Requested chat person not connected
eBadParameter (30046)	General problem with a parameter to a script call
eChatAlreadyListening (30047)	Already listening for incoming chats
eChatIDNotFound (30048)	Chat session with that ID not found
eChatAlreadyConnected (30049)	Already connected to that server/port
eClipboardEmpty (30050)	Cannot get (text from the) clipboard
eFileNotFound (30051)	Cannot open the specified file
eAlreadyTransferringFile (30052)	Already transferring a file
eNotTransferringFile (30053)	Not transferring a file
eNoSuchCommand (30054)	There is not a command of that name
eArrayAlreadyExists (30055)	That array already exists
eArrayDoesNotExist (30056)	That array does not exist
eBadKeyName (30056)	That name is not permitted for a key
eArrayNotEvenNumberOfValues (30057)	Values to be imported into array are not in pairs
eImportedWithDuplicates (30058)	Import succeeded, however some values were overwritten
eBadDelimiter (30059)	Import/export delimiter must be a single character, other than backslash
eSetReplacingExistingValue (30060)	Array element set, existing value overwritten
eKeyDoesNotExist (30061)	Array key does not exist
eCannotImport (30062)	Cannot import because cannot find unused temporary character
eItemInUse (30063)	Cannot delete trigger/alias/timer because it is executing a script
eSpellCheckNotActive (30064)	Spell checker is not active
eCannotAddFont (30065)	Cannot create requested font
ePenStyleNotValid (30066)	Invalid settings for pen parameter
eUnableToLoadImage (30067)	Bitmap image could not be loaded
eImageNotInstalled (30068)	Image has not been loaded into window
eInvalidNumberOfPoints (30069)	Number of points supplied is incorrect
eInvalidPoint (30070)	Point is not numeric
eHotspotPluginChanged (30071)	Hotspot processing must all be in same plugin
eHotspotNotInstalled (30072)	Hotspot has not been defined for this window
eNoSuchWindow (30073)	Requested miniwindow does not exist
eBrushStyleNotValid (30074)	Invalid settings for brush parameter

You can copy the error codes from the appropriate section below and paste into the start of your script file, to predefine all known return codes.

Error codes ready for use in VBscript programs

const eOK = 0 ' No error

const eWorldOpen = 30001 ' The world is already open

const eWorldClosed = 30002 ' The world is closed, this action cannot be performed

const eNoNameSpecified = 30003 ' No name has been specified where one is required

const eCannotPlaySound = 30004 ' The sound file could not be played

const eTriggerNotFound = 30005 ' The specified trigger name does not exist

const eTriggerAlreadyExists = 30006 ' Attempt to add a trigger that already exists

const eTriggerCannotBeEmpty = 30007 ' The trigger "match" string cannot be empty

const eInvalidObjectLabel = 30008 ' The name of this object is invalid

const eScriptNameNotLocated = 30009 ' Script name is not in the script file

const eAliasNotFound = 30010 ' The specified alias name does not exist

const eAliasAlreadyExists = 30011 ' Attempt to add a alias that already exists

const eAliasCannotBeEmpty = 30012 ' The alias "match" string cannot be empty

const eCouldNotOpenFile = 30013 ' Unable to open requested file

const eLogFileNotOpen = 30014 ' Log file was not open

const eLogFileAlreadyOpen = 30015 ' Log file was already open

const eLogFileBadWrite = 30016 ' Bad write to log file

const eTimerNotFound = 30017 ' The specified timer name does not exist

const eTimerAlreadyExists = 30018 ' Attempt to add a timer that already exists

const eVariableNotFound = 30019 ' Attempt to delete a variable that does not exist

const eCommandNotEmpty = 30020 ' Attempt to use SetCommand with a non-empty command window

const eBadRegularExpression = 30021 ' Bad regular expression syntax

const eTimeInvalid = 30022 ' Time given to AddTimer is invalid

const eBadMapItem = 30023 ' Direction given to AddToMapper is invalid

const eNoMapItems = 30024 ' No items in mapper

const eUnknownOption = 30025 ' Option name not found

const eOptionOutOfRange = 30026 ' New value for option is out of range

const eTriggerSequenceOutOfRange = 30027 ' Trigger sequence value invalid

const eTriggerSendToInvalid = 30028 ' Where to send trigger text to is invalid

const eTriggerLabelNotSpecified = 30029 ' Trigger label not specified/invalid for 'send to variable'

const ePluginFileNotFound = 30030 ' File name specified for plugin not found

const eProblemsLoadingPlugin = 30031 ' There was a parsing or other problem loading the plugin

const ePluginCannotSetOption = 30032 ' Plugin is not allowed to set this option

const ePluginCannotGetOption = 30033 ' Plugin is not allowed to get this option

const eNoSuchPlugin = 30034 ' Requested plugin is not installed

const eNotAPlugin = 30035 ' Only a plugin can do this

const eNoSuchRoutine = 30036 ' Plugin does not support that subroutine (subroutine not in script)

const ePluginCouldNotSaveState = 30037 ' Plugin could not save state (eg. no state directory)

const ePluginDoesNotSaveState = 30037 ' Plugin does not support saving state

const ePluginDisabled = 30039 ' Plugin is currently disabled

const eErrorCallingPluginRoutine = 30040 ' Could not call plugin routine

const eCommandsNestedTooDeeply = 30041 ' Calls to "Execute" nested too deeply

const eCannotCreateChatSocket = 30042 ' Unable to create socket for chat connection

const eCannotLookupDomainName = 30043 ' Unable to do DNS (domain name) lookup for chat connection

const eNoChatConnections = 30044 ' No chat connections open

const eChatPersonNotFound = 30045 ' Requested chat person not connected

const eBadParameter = 30046 ' General problem with a parameter to a script call

const eChatAlreadyListening = 30047 ' Already listening for incoming chats

const eChatIDNotFound = 30048 ' Chat session with that ID not found

const eChatAlreadyConnected = 30049 ' Already connected to that server/port

const eClipboardEmpty = 30050 ' Cannot get (text from the) clipboard

const eFileNotFound = 30051 ' Cannot open the specified file

const eAlreadyTransferringFile = 30052 ' Already transferring a file

const eNotTransferringFile = 30053 ' Not transferring a file

const eNoSuchCommand = 30054 ' There is not a command of that name

const eArrayAlreadyExists = 30055 ' That array already exists

const eArrayDoesNotExist = 30056 ' That array does not exist

const eBadKeyName = 30056 ' That name is not permitted for a key

const eArrayNotEvenNumberOfValues = 30057 ' Values to be imported into array are not in pairs

const eImportedWithDuplicates = 30058 ' Import succeeded, however some values were overwritten

const eBadDelimiter = 30059 ' Import/export delimiter must be a single character, other than backslash

const eSetReplacingExistingValue = 30060 ' Array element set, existing value overwritten

const eKeyDoesNotExist = 30061 ' Array key does not exist

const eCannotImport = 30062 ' Cannot import because cannot find unused temporary character

const eItemInUse = 30063 ' Cannot delete trigger/alias/timer because it is executing a script

const eSpellCheckNotActive = 30064 ' Spell checker is not active

const eCannotAddFont = 30065 ' Cannot create requested font

const ePenStyleNotValid = 30066 ' Invalid settings for pen parameter

const eUnableToLoadImage = 30067 ' Bitmap image could not be loaded

const eImageNotInstalled = 30068 ' Image has not been loaded into window

const eInvalidNumberOfPoints = 30069 ' Number of points supplied is incorrect

const eInvalidPoint = 30070 ' Point is not numeric

const eHotspotPluginChanged = 30071 ' Hotspot processing must all be in same plugin

const eHotspotNotInstalled = 30072 ' Hotspot has not been defined for this window

const eNoSuchWindow = 30073 ' Requested miniwindow does not exist

const eBrushStyleNotValid = 30074 ' Invalid settings for brush parameter

Error codes ready for use in JScript programs

var eOK = 0; // No error

var eWorldOpen = 30001; // The world is already open

var eWorldClosed = 30002; // The world is closed, this action cannot be performed

var eNoNameSpecified = 30003; // No name has been specified where one is required

var eCannotPlaySound = 30004; // The sound file could not be played

var eTriggerNotFound = 30005; // The specified trigger name does not exist

var eTriggerAlreadyExists = 30006; // Attempt to add a trigger that already exists

var eTriggerCannotBeEmpty = 30007; // The trigger "match" string cannot be empty

var eInvalidObjectLabel = 30008; // The name of this object is invalid

var eScriptNameNotLocated = 30009; // Script name is not in the script file

var eAliasNotFound = 30010; // The specified alias name does not exist

var eAliasAlreadyExists = 30011; // Attempt to add a alias that already exists

var eAliasCannotBeEmpty = 30012; // The alias "match" string cannot be empty

var eCouldNotOpenFile = 30013; // Unable to open requested file

var eLogFileNotOpen = 30014; // Log file was not open

var eLogFileAlreadyOpen = 30015; // Log file was already open

var eLogFileBadWrite = 30016; // Bad write to log file

var eTimerNotFound = 30017; // The specified timer name does not exist

var eTimerAlreadyExists = 30018; // Attempt to add a timer that already exists

var eVariableNotFound = 30019; // Attempt to delete a variable that does not exist

var eCommandNotEmpty = 30020; // Attempt to use SetCommand with a non-empty command window

var eBadRegularExpression = 30021; // Bad regular expression syntax

var eTimeInvalid = 30022; // Time given to AddTimer is invalid

var eBadMapItem = 30023; // Direction given to AddToMapper is invalid

var eNoMapItems = 30024; // No items in mapper

var eUnknownOption = 30025; // Option name not found

var eOptionOutOfRange = 30026; // New value for option is out of range

var eTriggerSequenceOutOfRange = 30027; // Trigger sequence value invalid

var eTriggerSendToInvalid = 30028; // Where to send trigger text to is invalid

var eTriggerLabelNotSpecified = 30029; // Trigger label not specified/invalid for 'send to variable'

var ePluginFileNotFound = 30030; // File name specified for plugin not found

var eProblemsLoadingPlugin = 30031; // There was a parsing or other problem loading the plugin

var ePluginCannotSetOption = 30032; // Plugin is not allowed to set this option

var ePluginCannotGetOption = 30033; // Plugin is not allowed to get this option

var eNoSuchPlugin = 30034; // Requested plugin is not installed

var eNotAPlugin = 30035; // Only a plugin can do this

var eNoSuchRoutine = 30036; // Plugin does not support that subroutine (subroutine not in script)

var ePluginCouldNotSaveState = 30037; // Plugin could not save state (eg. no state directory)

var ePluginDoesNotSaveState = 30037; // Plugin does not support saving state

var ePluginDisabled = 30039; // Plugin is currently disabled

var eErrorCallingPluginRoutine = 30040; // Could not call plugin routine

var eCommandsNestedTooDeeply = 30041; // Calls to "Execute" nested too deeply

var eCannotCreateChatSocket = 30042; // Unable to create socket for chat connection

var eCannotLookupDomainName = 30043; // Unable to do DNS (domain name) lookup for chat connection

var eNoChatConnections = 30044; // No chat connections open

var eChatPersonNotFound = 30045; // Requested chat person not connected

var eBadParameter = 30046; // General problem with a parameter to a script call

var eChatAlreadyListening = 30047; // Already listening for incoming chats

var eChatIDNotFound = 30048; // Chat session with that ID not found

var eChatAlreadyConnected = 30049; // Already connected to that server/port

var eClipboardEmpty = 30050; // Cannot get (text from the) clipboard

var eFileNotFound = 30051; // Cannot open the specified file

var eAlreadyTransferringFile = 30052; // Already transferring a file

var eNotTransferringFile = 30053; // Not transferring a file

var eNoSuchCommand = 30054; // There is not a command of that name

var eArrayAlreadyExists = 30055; // That array already exists

var eArrayDoesNotExist = 30056; // That array does not exist

var eBadKeyName = 30056; // That name is not permitted for a key

var eArrayNotEvenNumberOfValues = 30057; // Values to be imported into array are not in pairs

var eImportedWithDuplicates = 30058; // Import succeeded, however some values were overwritten

var eBadDelimiter = 30059; // Import/export delimiter must be a single character, other than backslash

var eSetReplacingExistingValue = 30060; // Array element set, existing value overwritten

var eKeyDoesNotExist = 30061; // Array key does not exist

var eCannotImport = 30062; // Cannot import because cannot find unused temporary character

var eItemInUse = 30063; // Cannot delete trigger/alias/timer because it is executing a script

var eSpellCheckNotActive = 30064; // Spell checker is not active

var eCannotAddFont = 30065; // Cannot create requested font

var ePenStyleNotValid = 30066; // Invalid settings for pen parameter

var eUnableToLoadImage = 30067; // Bitmap image could not be loaded

var eImageNotInstalled = 30068; // Image has not been loaded into window

var eInvalidNumberOfPoints = 30069; // Number of points supplied is incorrect

var eInvalidPoint = 30070; // Point is not numeric

var eHotspotPluginChanged = 30071; // Hotspot processing must all be in same plugin

var eHotspotNotInstalled = 30072; // Hotspot has not been defined for this window

var eNoSuchWindow = 30073; // Requested miniwindow does not exist

var eBrushStyleNotValid = 30074; // Invalid settings for brush parameter

Error codes ready for use in PerlScript programs

my $eOK = 0; # No error

my $eWorldOpen = 30001; # The world is already open

my $eWorldClosed = 30002; # The world is closed, this action cannot be performed

my $eNoNameSpecified = 30003; # No name has been specified where one is required

my $eCannotPlaySound = 30004; # The sound file could not be played

my $eTriggerNotFound = 30005; # The specified trigger name does not exist

my $eTriggerAlreadyExists = 30006; # Attempt to add a trigger that already exists

my $eTriggerCannotBeEmpty = 30007; # The trigger "match" string cannot be empty

my $eInvalidObjectLabel = 30008; # The name of this object is invalid

my $eScriptNameNotLocated = 30009; # Script name is not in the script file

my $eAliasNotFound = 30010; # The specified alias name does not exist

my $eAliasAlreadyExists = 30011; # Attempt to add a alias that already exists

my $eAliasCannotBeEmpty = 30012; # The alias "match" string cannot be empty

my $eCouldNotOpenFile = 30013; # Unable to open requested file

my $eLogFileNotOpen = 30014; # Log file was not open

my $eLogFileAlreadyOpen = 30015; # Log file was already open

my $eLogFileBadWrite = 30016; # Bad write to log file

my $eTimerNotFound = 30017; # The specified timer name does not exist

my $eTimerAlreadyExists = 30018; # Attempt to add a timer that already exists

my $eVariableNotFound = 30019; # Attempt to delete a variable that does not exist

my $eCommandNotEmpty = 30020; # Attempt to use SetCommand with a non-empty command window

my $eBadRegularExpression = 30021; # Bad regular expression syntax

my $eTimeInvalid = 30022; # Time given to AddTimer is invalid

my $eBadMapItem = 30023; # Direction given to AddToMapper is invalid

my $eNoMapItems = 30024; # No items in mapper

my $eUnknownOption = 30025; # Option name not found

my $eOptionOutOfRange = 30026; # New value for option is out of range

my $eTriggerSequenceOutOfRange = 30027; # Trigger sequence value invalid

my $eTriggerSendToInvalid = 30028; # Where to send trigger text to is invalid

my $eTriggerLabelNotSpecified = 30029; # Trigger label not specified/invalid for 'send to variable'

my $ePluginFileNotFound = 30030; # File name specified for plugin not found

my $eProblemsLoadingPlugin = 30031; # There was a parsing or other problem loading the plugin

my $ePluginCannotSetOption = 30032; # Plugin is not allowed to set this option

my $ePluginCannotGetOption = 30033; # Plugin is not allowed to get this option

my $eNoSuchPlugin = 30034; # Requested plugin is not installed

my $eNotAPlugin = 30035; # Only a plugin can do this

my $eNoSuchRoutine = 30036; # Plugin does not support that subroutine (subroutine not in script)

my $ePluginCouldNotSaveState = 30037; # Plugin could not save state (eg. no state directory)

my $ePluginDoesNotSaveState = 30037; # Plugin does not support saving state

my $ePluginDisabled = 30039; # Plugin is currently disabled

my $eErrorCallingPluginRoutine = 30040; # Could not call plugin routine

my $eCommandsNestedTooDeeply = 30041; # Calls to "Execute" nested too deeply

my $eCannotCreateChatSocket = 30042; # Unable to create socket for chat connection

my $eCannotLookupDomainName = 30043; # Unable to do DNS (domain name) lookup for chat connection

my $eNoChatConnections = 30044; # No chat connections open

my $eChatPersonNotFound = 30045; # Requested chat person not connected

my $eBadParameter = 30046; # General problem with a parameter to a script call

my $eChatAlreadyListening = 30047; # Already listening for incoming chats

my $eChatIDNotFound = 30048; # Chat session with that ID not found

my $eChatAlreadyConnected = 30049; # Already connected to that server/port

my $eClipboardEmpty = 30050; # Cannot get (text from the) clipboard

my $eFileNotFound = 30051; # Cannot open the specified file

my $eAlreadyTransferringFile = 30052; # Already transferring a file

my $eNotTransferringFile = 30053; # Not transferring a file

my $eNoSuchCommand = 30054; # There is not a command of that name

my $eArrayAlreadyExists = 30055; # That array already exists

my $eArrayDoesNotExist = 30056; # That array does not exist

my $eBadKeyName = 30056; # That name is not permitted for a key

my $eArrayNotEvenNumberOfValues = 30057; # Values to be imported into array are not in pairs

my $eImportedWithDuplicates = 30058; # Import succeeded, however some values were overwritten

my $eBadDelimiter = 30059; # Import/export delimiter must be a single character, other than backslash

my $eSetReplacingExistingValue = 30060; # Array element set, existing value overwritten

my $eKeyDoesNotExist = 30061; # Array key does not exist

my $eCannotImport = 30062; # Cannot import because cannot find unused temporary character

my $eItemInUse = 30063; # Cannot delete trigger/alias/timer because it is executing a script

my $eSpellCheckNotActive = 30064; # Spell checker is not active

my $eCannotAddFont = 30065; # Cannot create requested font

my $ePenStyleNotValid = 30066; # Invalid settings for pen parameter

my $eUnableToLoadImage = 30067; # Bitmap image could not be loaded

my $eImageNotInstalled = 30068; # Image has not been loaded into window

my $eInvalidNumberOfPoints = 30069; # Number of points supplied is incorrect

my $eInvalidPoint = 30070; # Point is not numeric

my $eHotspotPluginChanged = 30071; # Hotspot processing must all be in same plugin

my $eHotspotNotInstalled = 30072; # Hotspot has not been defined for this window

my $eNoSuchWindow = 30073; # Requested miniwindow does not exist

my $eBrushStyleNotValid = 30074; # Invalid settings for brush parameter

Error codes ready for use in Python programs

eOK = 0 # No error

eWorldOpen = 30001 # The world is already open

eWorldClosed = 30002 # The world is closed, this action cannot be performed

eNoNameSpecified = 30003 # No name has been specified where one is required

eCannotPlaySound = 30004 # The sound file could not be played

eTriggerNotFound = 30005 # The specified trigger name does not exist

eTriggerAlreadyExists = 30006 # Attempt to add a trigger that already exists

eTriggerCannotBeEmpty = 30007 # The trigger "match" string cannot be empty

eInvalidObjectLabel = 30008 # The name of this object is invalid

eScriptNameNotLocated = 30009 # Script name is not in the script file

eAliasNotFound = 30010 # The specified alias name does not exist

eAliasAlreadyExists = 30011 # Attempt to add a alias that already exists

eAliasCannotBeEmpty = 30012 # The alias "match" string cannot be empty

eCouldNotOpenFile = 30013 # Unable to open requested file

eLogFileNotOpen = 30014 # Log file was not open

eLogFileAlreadyOpen = 30015 # Log file was already open

eLogFileBadWrite = 30016 # Bad write to log file

eTimerNotFound = 30017 # The specified timer name does not exist

eTimerAlreadyExists = 30018 # Attempt to add a timer that already exists

eVariableNotFound = 30019 # Attempt to delete a variable that does not exist

eCommandNotEmpty = 30020 # Attempt to use SetCommand with a non-empty command window

eBadRegularExpression = 30021 # Bad regular expression syntax

eTimeInvalid = 30022 # Time given to AddTimer is invalid

eBadMapItem = 30023 # Direction given to AddToMapper is invalid

eNoMapItems = 30024 # No items in mapper

eUnknownOption = 30025 # Option name not found

eOptionOutOfRange = 30026 # New value for option is out of range

eTriggerSequenceOutOfRange = 30027 # Trigger sequence value invalid

eTriggerSendToInvalid = 30028 # Where to send trigger text to is invalid

eTriggerLabelNotSpecified = 30029 # Trigger label not specified/invalid for 'send to variable'

ePluginFileNotFound = 30030 # File name specified for plugin not found

eProblemsLoadingPlugin = 30031 # There was a parsing or other problem loading the plugin

ePluginCannotSetOption = 30032 # Plugin is not allowed to set this option

ePluginCannotGetOption = 30033 # Plugin is not allowed to get this option

eNoSuchPlugin = 30034 # Requested plugin is not installed

eNotAPlugin = 30035 # Only a plugin can do this

eNoSuchRoutine = 30036 # Plugin does not support that subroutine (subroutine not in script)

ePluginCouldNotSaveState = 30037 # Plugin could not save state (eg. no state directory)

ePluginDoesNotSaveState = 30037 # Plugin does not support saving state

ePluginDisabled = 30039 # Plugin is currently disabled

eErrorCallingPluginRoutine = 30040 # Could not call plugin routine

eCommandsNestedTooDeeply = 30041 # Calls to "Execute" nested too deeply

eCannotCreateChatSocket = 30042 # Unable to create socket for chat connection

eCannotLookupDomainName = 30043 # Unable to do DNS (domain name) lookup for chat connection

eNoChatConnections = 30044 # No chat connections open

eChatPersonNotFound = 30045 # Requested chat person not connected

eBadParameter = 30046 # General problem with a parameter to a script call

eChatAlreadyListening = 30047 # Already listening for incoming chats

eChatIDNotFound = 30048 # Chat session with that ID not found

eChatAlreadyConnected = 30049 # Already connected to that server/port

eClipboardEmpty = 30050 # Cannot get (text from the) clipboard

eFileNotFound = 30051 # Cannot open the specified file

eAlreadyTransferringFile = 30052 # Already transferring a file

eNotTransferringFile = 30053 # Not transferring a file

eNoSuchCommand = 30054 # There is not a command of that name

eArrayAlreadyExists = 30055 # That array already exists

eArrayDoesNotExist = 30056 # That array does not exist

eBadKeyName = 30056 # That name is not permitted for a key

eArrayNotEvenNumberOfValues = 30057 # Values to be imported into array are not in pairs

eImportedWithDuplicates = 30058 # Import succeeded, however some values were overwritten

eBadDelimiter = 30059 # Import/export delimiter must be a single character, other than backslash

eSetReplacingExistingValue = 30060 # Array element set, existing value overwritten

eKeyDoesNotExist = 30061 # Array key does not exist

eCannotImport = 30062 # Cannot import because cannot find unused temporary character

eItemInUse = 30063 # Cannot delete trigger/alias/timer because it is executing a script

eSpellCheckNotActive = 30064 # Spell checker is not active

eCannotAddFont = 30065 # Cannot create requested font

ePenStyleNotValid = 30066 # Invalid settings for pen parameter

eUnableToLoadImage = 30067 # Bitmap image could not be loaded

eImageNotInstalled = 30068 # Image has not been loaded into window

eInvalidNumberOfPoints = 30069 # Number of points supplied is incorrect

eInvalidPoint = 30070 # Point is not numeric

eHotspotPluginChanged = 30071 # Hotspot processing must all be in same plugin

eHotspotNotInstalled = 30072 # Hotspot has not been defined for this window

eNoSuchWindow = 30073 # Requested miniwindow does not exist

eBrushStyleNotValid = 30074 # Invalid settings for brush parameter

See also ...

Script information

Scripting functions list

See Also ...

Topic

 Scripting

(Help topic: general=errors)


Sending to the world

There are various ways of sending commands to the MUD. The main ways are:

•	Sending in the usual way, which may append to any existing speedwalk queue

•	Queueing up a command to go at the speedwalk rate

•	Sending immediately, bypassing the speedwalk queue

See Also ...

Topic

 Commented softcode

Functions

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: general=send)


Speed walking

Speed walking is a way of quickly moving from one location to another. You can choose a "speed walk" prefix (for example, "#"). Once you have done that, and enabled speed walking in the "commands" configuration screen, then you can speed walk by entering the prefix followed by a string of direction letters, like this:

#4n3esuwdLW

This would move you: 4 times North, 3 times East, South, Up, West, Down and then "lock west"

Actions

Actions recognised are: C:close; O:open; L:lock; K:unlock (or nothing for no special action, just walk in that direction)

Directions

The directions recognised are: N:north, S:south, E:east, W:west, U:up, D:down (not case-sensitive).

Filler

You can also enter "F" for a speed walk "filler". This is for MUDs that reject multiple identical commands. For example, if you need to walk West 30 times, but your MUD disconnects you after 20 identical commands, enter:

#15w f 15w

The exact text that is sent by the "filler" is customisable from the "Input" world configuration screen. A suggested filler command would be something harmless, like LOOK.

Multipliers

You may also enter a one or two-digit multiplier in the range 1 to 99. The multiplier affects the *next* direction entered, e.g. "5s" means go South 5 times.

Spaces are accepted in the speed walk command, and ignored.

Special commands

If you need to enter other directions or commands (eg. NE for NorthEast) then you can put them in brackets. Otherwise, NE would be North, followed by East. Thus, to you North, West, and then NorthEast, you would enter:

N W (NE)

To allow for reversing a speedwalk, you can also put the reverse direction after a slash. For example:

(NE/SW) (UP/DOWN) (OPEN/CLOSE) (LOCK/UNLOCK)

By doing this if you choose to reverse a speedwalk alias, all of the special commands will reverse correctly.

Comments

You can put comments into a speedwalk by putting it in braces, like this:

{ The Hall of the Mountain King }

This lets you describe what point you are up to in a lengthy speedwalk.

Speed walk delay

You can specify a time, between 0 and 30,000 milliseconds (that is, zero to 30 seconds) as a delay between each direction being sent to the MUD. This is for MUDs that don't allow very rapid walking. 1,000 milliseconds represent one second, so to have a 1.5 second delay, you would enter 1500 as the delay in milliseconds.

If you are using delayed speedwalking, any outstanding speedwalk (or other) commands are shown on the status line (up to a maximum of 50 characters). If there are more than 50 characters outstanding, you will see "..." following the speedwalk string.

If you change your mind about speedwalking (while some directions are still queued), you can use Discard queued commands to discard any queued commands.

Bypassing the speedwalk queue

You can set up an alias to "send to immediate" which will bypass the speedwalk queue. This lets you, for example, "say" to other players while you still have queued speedwalks.

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

Dialog

 Commands

Functions

 EvaluateSpeedwalk (Evaluates a speed walk string)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 ReverseSpeedwalk (Reverses a speed walk string)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: general=speed_walking)


Spell checker

MUSHclient has an inbuilt spell checker (supplied as a separate DLL file).

You can use this in various ways:

•	 Spell check each command automatically before it is sent

•	 Spell check commands on request (by keystroke or menu option)

•	 Spell check arbitrary text from scripting

•	 Spell check the command window on request from scripting

See Also ...

Command

 SpellCheck (Spell checks the command in the command window)

Dialogs

 New Spell-Check Dictionary

 Spell Check

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: general=spellcheck)


Timers

Timers let you set up periodic events (eg. every 10 seconds) or things that happen at a particular time (eg. 10:30 a.m.)

Timers can be once-off, which means they fire once and then delete themselves. This is useful if you only need to do the timed event once. (eg. cast a spell in 10 seconds).

Alternatively, timers can fire indefinitely, so you might, for example, eat food every 10 minutes.

Timers can send text to the MUD, make a note in the output window, invoke a script, do a speedwalk, or many other things.

You can have any number of timers, per world.

Granularity of timers

Note that the "granularity" of the timers is controlled by the "timers" tab in the "Preferences" menu item under the File menu.

What this means is that the interval set there (eg. 5 seconds) is the rate at which timers are tested to see if they have fired. If you want timers to be accurate to the nearest second, then the timer granularity must be set at 1 second. If having a timer fire to the nearest 5 seconds is satisfactory for you, then set the granularity to 5 seconds. Setting a smaller granularity improves the accuracy of timers, but may slow the program down slightly, particularly on slower PCs.

You can have timers tested every 10th of a second by setting the granularity to zero in the global preferences. This allows for finer resolution of timers than was previously possible.

Timer scripts

Timers can execute script commands by simply putting the command into the "send" box and selecting "send to script".

However for more complex scripts you can put scripts into your script file (see scripting configuration tab for the world) and then call the script from the timer. To do this put the name of the script subroutine into the alias's script box.

The script subroutine must have one argument which is the name of the timer.

An example script in the VBscript language would be:

sub MyTimer (name)

  world.Note "Timer " & name & " fired."

end sub

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Triggers

Command

 ConfigureTimers (Define timers)

Dialogs

 Edit timer

 Timers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: general=timers)


Triggers

What is a trigger exactly?

Triggers match on something received from the MUD. They trigger some sort of action by MUSHclient, hence their name.

They have a counterpart that matches on what you type, called an "alias".

What can I do with triggers?

  •	Colour a line to make it stand out (eg. colour chat channels in blue)

  •	Colour individual words to make them stand out (eg. colour your character's name)

  •	Highlight lines or words in bold, italic or underline

  •	Gag annoying players by discarding lines which contain messages from them

  •	Omit uninteresting things from the log file

  •	Play a sound when certain things happen

  •	Call a script routine to handle special events

  •	Send a response back to the MUD (eg. "wield sword" when you are attacked)

  •	Make editing attributes in a MUSH or MUCK easier

How do I get a trigger to match?

You normally match on incoming text, but you can also match on the colour of an incoming line.

There are two sorts of matches you can do:

  •	Normal, with wildcards

  •	Regular expression

Normal matching

A normal trigger (ie. with "regular expression" not checked) just matches on literally what is entered in the "Trigger" box, with optional wildcards represented by asterisks. You can have up to 999 asterisks, each representing some "unknown" text that might vary from line-to-line (eg. the name of someone or something).

For example:

  •	To match on pages: Rhayctred pages: I saw Ibydan down by the river.

  •	Trigger: * pages: *

  •	To match on emotes: From afar, Ocalef sighs

  •	Trigger: From afar, *

One restriction on normal triggers is that you can't match on the "*" character itself, as it is a wildcard symbol. To do that, you would need to use a regular expression (see below), and "escape" the "*" by putting a backslash in front of it.

For example, to match a line starting with an asterisk, you could match on this (with a regular expression):

^\*

Regular expression

Regular expressions are a bit more complex, but give you more power over what you match on.

A couple of simple rules:

•	^ - Matches the start of the line

•	$ - Matches the end of the line

•	. - Matches any character

•	* - Matches zero or more of the previous character or set (so, ".*" matches any number of anything)

•	+ - Matches one or more of the previous character or set (eg. "be+d" matches "bed", "beed", "beeed" and so on.)

Making regular expressions check for alternatives

Another powerful thing you can do with regular expressions is to look for "this" or "that".

For instance, if you want to make a trigger warn you if one of Cigowyr, Herrach, Crael or Wiceadric has paged you, you can match like this:

^(Cigowyr|Herrach|Crael|Wiceadric) pages\: .+$

The "|" symbol means "or", so the expression matches on one name or another. You can extend this idea to matching on whether they page or say something, like this:

^(Cigowyr|Herrach|Crael|Wiceadric) (pages\:|says,) .+$

You probably want to check "ignore case" in case their name is given as "cigowyr" rather than "Cigowyr".

How to gag annoying players

Simply set up a regular expression like the one above (substituting the relevant player names, of course), and then check "omit from output". Any paragraphs matching that trigger will be discarded from your output window.

If you want to let them know you have them gagged you could put something like this in the "Send" box:

page %1 = I am ignoring you.

Note - it might be unwise to set up an "auto-response" like the one above, because it could be used as the basis of a Denial Of Service (DOS) attack. If two players each set up an auto-response like that, then they will get into a loop, as the response from one player triggers the response from the other, and so on. Especially if they have "omit from output" set, they will not even be aware that they are causing a great overhead for the MUD, as it continually sends the messages backwards and forwards between the two players.

What you could do to guard against this would be to make the trigger call a script routine, and in the script count how many times it has been called. After (say) 20 times it could notify you (using world.note) or disable the trigger, so you could take corrective action (like complaining to an admin about the other player).

Matching on everything except a word

In some cases, you might want to match on everything except one word. For example, in SMAUG both room names and exits are displayed in white on black. You could detect room names by setting the match string like this:

Trigger: ^(?!Exits:).*$

Match: white on black, bold

Regular expression: Checked

The expression "(?!Exits:)" means not the word "Exits:".

Another real-life example was where a player wanted to congratulate other players when they reached another level, but not congratulate himself. He could do that like this:

Trigger: ^(?!Caeth )(\w*) has risen to .*$

Regular expression: Checked

Send: say Congratulations %1!

This example assumes the player's name is Caeth.

Trigger scripts

Triggers can execute script commands by simply putting the command into the "send" box and selecting "send to script".

However for more complex scripts you can put scripts into your script file (see scripting configuration tab for the world) and then call the script from the trigger. To do this put the name of the script subroutine into the trigger's script box.

The script subroutine must have three arguments (four for Lua), as follows:

•	Name of the trigger

•	The matching line

•	An array of the first 10 wildcards (Lua - all wildcards)

•	Lua only - a table of all the styles in the line

An example script in the VBscript language would be:

sub MyTrigger (name, line, wildcards)

  world.Note "Trigger " & name & " matched."

  world.Note "Wildcard 1 was" & wildcards (1)

end sub

Wildcard 10 is the entire matching sequence, which is not necessarily the same as the matching line in the case of regular expressions.

Other wildcards can be accessed by using the GetTriggerWildcard script routine (for example, named wildcards, or wildcards over number 9).

For Lua, wildcard 10 is the tenth wildcard, wildcard 11 is the eleventh wildcard and so on. All wildcards are returned in the Lua wildcards table. Wildcard subscript 0 is the entire matching line. Also in Lua named wildcards are returned in the wildcards table keyed by name.

For Lua, the fourth argument (which you can optionally supply) is returned with a table of each style run for the triggered line. Inside that table (which starts at 1 for the first style) is a table per style. Per style, you will get four entries:

•	textcolour - the RGB colour of the text in that style run

•	backcolour - the RGB colour of the background colour in that style run

•	text - the text of that style run

•	length - the length of that style run

•	style - style flags (or'ed together): bold=1, underline=2, blink=4.

Wildcards

A powerful feature in matching triggers or aliases is the ability to specify "wildcards" which are variable information that might change from time to time.

For example:

* attacks you.

In this case the asterisk represents the name of the unknown attacker.

Using the wildcard in the "send" box ...

To use this unknown quantity you can refer to it as %1 (for the first wildcard) in the "send" box, like this:

kick %1

The second wildcard is %2, and so on. Wildcard %0 is a special case which represents the entire matching text.

For wildcards above 9 you can use this syntax:

kick %<22>

The number in the angled brackets can be from 0 to 999.

Also, if you use regular expressions, you can name wildcards, like this:

^(?P<target>.*) attacks you\.$

This names the wildcard as "target". You can then use this name in a similar way:

kick %<target>

Trigger evaluation

Normally when a trigger matches, no further matching is done, for the main world, or the current plugin. That way a match "deals with" the current situation (eg. if your character is hungry). However if you check "keep evaluating" then further triggers in the list are evaluated as well.

Regardless of the "keep evaluating" flag, triggers in other plugins are still processed, as each plugin is supposed to be independent.

However a script can call the StopEvaluatingTriggers if it needs to stop further evaluation, either in the current plugin, or all plugins. This lets a script decide, at run-time, whether or not it handled the situation.

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

Commands

 ConfigureTriggers (Define triggers)

 TestTrigger (Test trigger evaluation)

Dialogs

 Edit trigger

 Highlight word

 Make Multi-Line Trigger

 Trigger configuration list

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: general=triggers)


Utilities

There are various utility functions built into MUSHclient, some of which are in the built-in notepad.

Follow the links below for more details.

See Also ...

Topic

 Scripting

Commands

 Base64Decode (Decodes Base-64 coding)

 Base64Encode (Encodes text into Base-64 coding)

 ConvertForumCodes (Converts text on the clipboard for use in the forum)

 ConvertHTMLspecial (Converts special HTML characters, eg. < to &lt;)

 DosToMac (Converts selection from DOS text to Mac text)

 DosToUnix (Converts selection from DOS text to Unix text)

 FunctionList (Shows a list of all scripting functions)

 GenerateCharacterName (Generates a random MUD character name)

 GenerateUniqueID (Generates a 24-character hashed unique string)

 KeyName (Converts a keypress into its name)

 MacToDos (Converts selection from Mac text to DOS text)

 QuoteForumCodes (Escapes the characters [, ], \ with a backslash.)

 QuoteLines (Adds '> ' to the start of each line)

 UnixToDos (Converts selection from Unix text to DOS text)

 UpperCase (Converts to all upper case)

Dialogs

 Choose from combo-box

 Choose from list box

 Colour picker

 Functions

 Generate Unique ID

 Input Box

 Input Edit Box

 Key name

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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: general=utils)


Variables

You can store any number of user-defined variables, which are "strings" - that is they can hold any text, including multiple lines. These are saved when you save the "world" file, so each world can remember things from one session to the next (eg. the names of potions you have found).

You can also store variables inside plugins. If the plugin is set to "save state" then any variables inside that plugin are automatically saved when the plugin closes.

See Also ...

Topics

 Arrays

 Plugins

 Scripting

Command

 ConfigureVariables (Sets program variables)

Dialogs

 Edit variable

 Variables configuration (list)

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: general=variables)


World functions

The "world" script functions let you obtain references to other open worlds which you can then use in your script to do things to them. For example, you could write your own "send to all worlds" script.

See Also ...

Topic

 Scripting

Functions

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: general=world)


Accelerator

Script function

world.Accelerator

 Read about scripting

Type

Method

Summary

Add or modify an accelerator key (keystroke to command mapping)

Prototype

long Accelerator(BSTR Key, BSTR Send);

 View list of data type meanings

Description

This lets you add or amend the behaviour of MUSHclient "accelerator" keys. For example, you could make Ctrl+E become "eat meat".

These changes only apply to the current world (the one the script function is run in). They override any existing macros or accelerator keys defined for MUSHclient's default behaviour.

You specify two arguments, the keystroke to add or amend, and the text to be sent. The text is sent to the MUSHclient command processor, and can thus contain aliases, speedwalks, script commands, or anything you might normally type into the command window.

For example, to execute a script simply prefix the script command with the scripting prefix. Or alternatively, make up a word you wouldn't normally type (like "SFDSHHG$%(&") and make an alias to match that. Then in the alias do whatever you want to do.

See also AcceleratorTo which lets you specify where to send the command (eg. script, speedwalk).

The keystroke consists of this syntax:

CTRL + ALT + SHIFT + key

The modifiers CTRL, ALT and SHIFT are all optional, and are not case-sensitive. They can appear in any order.

The key can be one of the following:

0 1 2 3 4 5 6 7 8 9

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Accept Add Apps Attn Backspace Cancel Capital Clear Control Convert Crsel Decimal Delete Divide Down End Enter Ereof Esc Execute Exsel F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24 Final Hangeul Hangul Hanja Help Home Insert Junja Kana Kanji LButton LControl LMenu LShift LWin Left MButton Menu ModeChange Multiply NonConvert Noname Numlock Numpad0 Numpad1 Numpad2 Numpad3 Numpad4 Numpad5 Numpad6 Numpad7 Numpad8 Numpad9 Oem_clear Pa1 PageDown PageUp Pause Play Print ProcessKey RButton RControl RMenu RShift RWin Right Scroll Select Separator Snapshot Space Subtract Tab Up Zoom

They are not all guaranteed to work in the way you might expect. These names were obtained from the Windows include files. Some keys may be trapped by the operating system, or not be available on your PC.

Reasonable values to use would be things like:

Alt+Down

Shift+Ctrl+F2

Ctrl+N

PageUp

Ctrl+PageUp

F5

Ctrl+Shift+F9

--------

To disable a previously-assigned accelerator, call this function with an empty string as the command. eg

Accelerator "Ctrl+K", ""  ' return to default behaviour

If you wanted to make a key simply "do nothing" then you will need to do something like send an empty script, or make a "do nothing" alias, and call that. eg.

Accelerator "Ctrl+K", "/"  ' execute empty script

Accelerator "Ctrl+K", "DO_NOTHING_ALIAS"  ' call an alias that does nothing

The "do nothing" alias might be the safer approach, in case someone has changed the scripting prefix to something other than "/".

----------

To see the name for a particular keypress use the Input menu -> Key Name dialog. This lets you type a key and have its name displayed. This name can then be used in this function.

Return value

eBadParameter - the keystroke combination was not accepted

eOK - added OK

 View list of return code meanings

Lua example

Accelerator ("Ctrl+K", "kill")

Accelerator ("Ctrl+F", "follow")

Accelerator ("Ctrl+E", "eat meat")

-- execute a script

Accelerator ("Ctrl+M", "/DoCommand 'preferences'")

Accelerator ("Ctrl+E", "") -- revert to original behaviour for Ctrl+E

Jscript example

Accelerator ("Ctrl+K", "kill")

Accelerator ("Ctrl+F", "follow")

Accelerator ("Ctrl+E", "eat meat")

Accelerator ("Alt+F2", "#4s 3e")  // speedwalk

PerlScript example

$world->Accelerator ("Ctrl+K", "kill")

$world->Accelerator ("Ctrl+F", "follow")

$world->Accelerator ("Ctrl+E", "eat meat")

$world->Accelerator ("Alt+F2", "#4s 3e")  # speedwalk

VBscript example

Accelerator "Ctrl+K", "kill"

Accelerator "Ctrl+F", "follow"

Accelerator "Ctrl+E", "eat meat"

Accelerator "Alt+F2", "/Note ""oops"""

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Functions

 AcceleratorList (List defined accelerators)

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: function=Accelerator)


AcceleratorList

Script function

world.AcceleratorList

 Read about scripting

Type

Method

Summary

List defined accelerators

Prototype

VARIANT AcceleratorList();

 View list of data type meanings

Description

Returns an array of all the accelerator keys currently defined, in the format:

keystroke = text<tab>[sendto]

eg.

Ctrl+E = eat meat<tab>[0]

Ctrl+F = follow

Ctrl+K = 4s 3e<tab>[11]

Ctrl+B = DoAfter(5, "sigh")<tab>[12]

If the "send to" field is "send to execute" (which is 10) then it is omitted (as in the "follow" example above), for backwards compatibility with versions of MUSHclient prior to 4.27.

Version 4.27 implemented the AcceleratorTo function, which lets you specify where the accelerator text is sent to.

If "send to" field is not 10 then the "send to" field number is specified as a number in square brackets at the end of the text, preceded by the tab character (hex 0x09).

The "SendTo" argument specifies where the text is to be sent to when you press the accelerator key. It can be one of:

0: World

1: Command window

2: Output window

3: Status line

4: Notepad (new)

5: Notepad (append)

6: Log File

7: Notepad (replace)

8: Command queue

9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit (send to script engine, after lines have been omitted)

Return value

If there are no accelerators defined then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the keystrokes and contents of each accelerator.

Use "lbound" and "ubound" to find the bounds of the array of list (ie. the number of accelerators in the list).

Lua example

-- simple example

for _, v in pairs (AcceleratorList ()) do

  Note (v)

end

-- complex example - filters on a supplied string

function FindCommand (what)

  -- search all accelerators for wanted string

  for _, v in pairs (AcceleratorList ()) do

    if string.find (string.upper (v), string.upper (what), 1, true) then

      print (v)

    end	-- if

  end  -- for

end   -- function

FindCommand "eat"

-- example of extracting out the keystroke, what is sent, and where it is sent:

accels = AcceleratorList ()

if accels then

  for _, v in ipairs (accels) do

    local keystroke, what, where = string.match (v, "^(%S+) = (.*)%[(%d-)%]$")

    if where then

       where = tonumber (where)

    else

       keystroke, what = string.match (v, "^(%S+) = (.*)$")

       where = sendto.execute

    end -- if

    print ("keystroke =", keystroke)

    print ("what =", what)

    print ("where =", where)

  end -- for

end -- if

-- another example that turns the result into an easier-to-use table:

local accels = AcceleratorList ()

local taccels = {}

if accels then

  for _, v in ipairs (accels) do

    local keystroke, what, where = string.match (v, "^(%S+) = (.*)%[(%d-)%]$")

    if where then

       where = tonumber (where)

    else

       keystroke, what = string.match (v, "^(%S+) = (.*)$")

       where = sendto.execute

    end -- if

    taccels [keystroke] = { send = what, where = where }

  end -- for

end -- if

tprint (taccels)

Lua notes

The example above shows how you might search for accelerators matching a particular string.

The latter examples shows extracting out the original keystroke, send text, and where it is sent.

Note that the accelerator list is numerically keyed, not keyed by the keystroke.

VBscript example

dim accList

arrList = world.AcceleratorList

If Not IsEmpty (accList) Then

  For Each a In arrList

    world.note a

  Next

End If

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorTo (Add or modify an accelerator key - with "Send To" parameter)

(Help topic: function=AcceleratorList)


AcceleratorTo

Script function

world.AcceleratorTo

 Read about scripting

Type

Method

Summary

Add or modify an accelerator key - with "Send To" parameter

Prototype

long AcceleratorTo(BSTR Key, BSTR Send, short SendTo);

 View list of data type meanings

Description

This lets you add or amend the behaviour of MUSHclient "accelerator" keys. For example, you could make Ctrl+E become "eat meat".

This is similar to the Accelerator function (see elsewhere), however this version allows you to specify where the "send text" is to be sent to (for example, to a script, to a speedwalk, to the output window).

These changes only apply to the current world (the one the script function is run in). They override any existing macros or accelerator keys defined for MUSHclient's default behaviour.

You specify three arguments, the keystroke to add or amend, the text to be sent, and where to send it.

The keystroke consists of this syntax:

CTRL + ALT + SHIFT + key

The modifiers CTRL, ALT and SHIFT are all optional, and are not case-sensitive. They can appear in any order.

The key can be one of the following:

0 1 2 3 4 5 6 7 8 9

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Accept Add Apps Attn Backspace Cancel Capital Clear Control Convert Crsel Decimal Delete Divide Down End Enter Ereof Esc Execute Exsel F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24 Final Hangeul Hangul Hanja Help Home Insert Junja Kana Kanji LButton LControl LMenu LShift LWin Left MButton Menu ModeChange Multiply NonConvert Noname Numlock Numpad0 Numpad1 Numpad2 Numpad3 Numpad4 Numpad5 Numpad6 Numpad7 Numpad8 Numpad9 Oem_clear Pa1 PageDown PageUp Pause Play Print ProcessKey RButton RControl RMenu RShift RWin Right Scroll Select Separator Snapshot Space Subtract Tab Up Zoom

They are not all guaranteed to work in the way you might expect. These names were obtained from the Windows include files. Some keys may be trapped by the operating system, or not be available on your PC.

Reasonable values to use would be things like:

Alt+Down

Shift+Ctrl+F2

Ctrl+N

PageUp

Ctrl+PageUp

F5

Ctrl+Shift+F9

--------

The "SendTo" argument specifies where the text is to be sent to. It can be one of:

0: World

1: Command window

2: Output window

3: Status line

4: Notepad (new)

5: Notepad (append)

6: Log File

7: Notepad (replace)

8: Command queue

9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit (send to script engine, after lines have been omitted)

The case "set variable" is not very useful because there is no way of specifying which variable to send to.

Use "send to script" if you want to set a variable (using the SetVariable function).

--------

To disable a previously-assigned accelerator, call this function with an empty string as the command. eg

AcceleratorTo ("Ctrl+K", "", 0) -- return to default behaviour

If you wanted to make a key simply "do nothing" then you will need to do something like send an empty script. eg.

AcceleratorTo ("Ctrl+K", "--", 12)  -- execute script with only a comment in it (Lua in this case)

----------

To see the name for a particular keypress use the Input menu -> Key Name dialog. This lets you type a key and have its name displayed. This name can then be used in this function.

Note: If you use AcceleratorTo inside a plugin, that plugin ID is remembered and becomes the current plugin (if possible) when the accelerator is pressed. Thus send-to-script is executed in the calling plugin's script space. If the plugin does not exist when the accelerator is pressed (eg. the plugin has been removed) then the accelerator does nothing. However send-to-execute works whether or not the original plugin still exists, for backwards compatibility with the original Accelerator function.

Return value

eBadParameter - the keystroke combination was not accepted

eOptionOutOfRange - the SendTo parameter was out of range

eOK - added OK

 View list of return code meanings

Lua example

AcceleratorTo ("Ctrl+K", "kill", sendto.world)

AcceleratorTo ("Ctrl+F", "follow", sendto.world)

AcceleratorTo ("Ctrl+E", string.rep ('-', 60), sendto.output)  -- 60 hyphens in output window

-- execute a script

AcceleratorTo ("Ctrl+M", "DoCommand 'preferences' ", sendto.script)  -- send to script

AcceleratorTo ("Ctrl+E", "") -- revert to original behaviour for Ctrl+E

Lua notes

The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

AcceleratorTo ("Ctrl+K", "kill", 0)

AcceleratorTo ("Ctrl+F", "follow", 0)

AcceleratorTo ("Ctrl+E", "eat meat", 0)

AcceleratorTo ("Alt+F2", "4s 3e", 11)  // speedwalk

PerlScript example

$world->AcceleratorTo ("Ctrl+K", "kill", 0)

$world->AcceleratorTo ("Ctrl+F", "follow", 0)

$world->AcceleratorTo ("Ctrl+E", "eat meat", 0)

$world->AcceleratorTo ("Alt+F2", "4s 3e", 11)  # speedwalk

VBscript example

AcceleratorTo "Ctrl+K", "kill", 0

AcceleratorTo "Ctrl+F", "follow", 0

AcceleratorTo "Ctrl+E", "eat meat", 0

AcceleratorTo "Alt+F2", "Note ""oops""", 12

See Also ...

Topics

 Aliases

 Keypad navigation

 Macro keys

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 AcceleratorList (List defined accelerators)

(Help topic: function=AcceleratorTo)


Activate

Script function

world.Activate

 Read about scripting

Type

Method

Summary

Activates the world window

Prototype

void Activate();

 View list of data type meanings

Description

Activates the main (first) window for this world. If you have multiple windows open then the first one created will be activated.

Return value

Nothing.

Lua example

Activate()

Jscript example

world.activate();

PerlScript example

$world->activate;

Python example

world.activate

VBscript example

world.activate

See Also ...

Functions

 ActivateClient (Activates the main MUSHclient window)

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 Open (Opens a named document)

 ReplaceNotepad (Replaces text in a notepad window)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=Activate)


ActivateClient

Script function

world.ActivateClient

 Read about scripting

Type

Method

Summary

Activates the main MUSHclient window

Prototype

void ActivateClient();

 View list of data type meanings

Description

Activates the main MUSHclient window, effectively bringing MUSHclient to the front as the active application.

Return value

Nothing.

Lua example

ActivateClient()

Jscript example

world.ActivateClient();

PerlScript example

$world->ActivateClient;

Python example

world.ActivateClient

VBscript example

world.ActivateClient

See Also ...

Function

 Activate (Activates the world window)

(Help topic: function=ActivateClient)


ActivateNotepad

Script function

world.ActivateNotepad

 Read about scripting

Type

Method

Summary

Activates a notepad window

Prototype

boolean ActivateNotepad(BSTR Title);

 View list of data type meanings

Description

Activates (makes the active window) the notepad window of the given title.

Return value

0: Could not do it.

1:  Activated OK

Lua example

ActivateNotepad("Nick's window")

Jscript example

world.ActivateNotepad("Nick's window");

PerlScript example

$world->ActivateNotepad("Nick's window");

Python example

world.ActivateNotepad("Nick's window")

VBscript example

world.ActivateNotepad "Nick's window"

See Also ...

Topic

 Notepad

Functions

 Activate (Activates the world window)

 ActivateClient (Activates the main MUSHclient window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=ActivateNotepad)


AddAlias

Script function

world.AddAlias

 Read about scripting

Type

Method

Summary

Adds an alias

Prototype

long AddAlias(BSTR AliasName, BSTR MatchText, BSTR ResponseText, long Flags, BSTR ScriptName);

 View list of data type meanings

Description

Adds a alias to the list of aliases.

Name: name of this alias - may be empty (see rules for names below)

Match_text: what to match on

Response_text: what to send to the world

Flags: various flags, see list below

ScriptName: Which script subroutine to execute

Flags

The flags can be one or more of the constants below. For example, to enable the alias, and ignore the case of what was typed, the flags would be 33. Preferably use the constant declarations in your script file, and "OR" them together. E.g.

VBscript: eEnabled or eIgnoreAliasCase

JScript:  eEnabled | eIgnoreAliasCase

VBscript constants:

const eEnabled = 1  ' enable alias

const eKeepEvaluating = 8 ' keep evaluating

const eIgnoreAliasCase = 32  ' ignore case when matching

const eOmitFromLogFile = 64  ' omit this alias from the log file

const eAliasRegularExpression = 128 ' alias is regular expressions

const eExpandVariables = 512  ' expand variables like @direction

const eReplace = 1024  ' replace existing alias of same name

const eAliasSpeedWalk = 2048  ' interpret send string as a speed walk string

const eAliasQueue = 4096  ' queue this alias for sending at the speedwalking delay interval

const eAliasMenu = 8192  ' this alias appears on the alias menu

const eTemporary = 16384 ' temporary - do not save to world file

JScript constants:

var eEnabled = 1;   // same as for AddTrigger

var eKeepEvaluating = 8; // keep evaluating

var eIgnoreAliasCase = 32; //  ignore case when matching

var eOmitFromLogFile = 64; // omit this alias from the log file

var eAliasRegularExpression = 128; // alias is regular expressions

var eExpandVariables = 512;  // expand variables like @direction

var eReplace = 1024;  //  replace existing alias of same name

var eAliasSpeedWalk = 2048;  // interpret send string as a speed walk string

var eAliasQueue = 4096;  // queue this alias for sending at the speedwalking delay interval

var eAliasMenu = 8192; //  this alias appears on the alias menu

var eTemporary = 16384; // temporary - do not save to world file

PerlScript constants:

my $eEnabled = 1;   # same as for AddTrigger

my $eKeepEvaluating = 8; # keep evaluating

my $eIgnoreAliasCase = 32; #  ignore case when matching

my $eOmitFromLogFile = 64; # omit this alias from the log file

my $eAliasRegularExpression = 128; # alias is regular expressions

my $eExpandVariables = 512;  # expand variables like @direction

my $eReplace = 1024;  #  replace existing alias of same name

my $eAliasSpeedWalk = 2048; # interpret send string as a speed walk string

my $eAliasQueue = 4096;  # queue this alias for sending at the speedwalking delay interval

my $eAliasMenu = 8192; #  this alias appears on the alias menu

my $eTemporary = 16384;  # temporary - do not save to world file

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasAlreadyExists: A alias of that name already exists

eAliasCannotBeEmpty: The "match_text" cannot be empty

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

eOK: added OK

 View list of return code meanings

Lua example

AddAlias("food_alias", "eat", "eat food", alias_flag.Enabled, "")

Lua notes

The script name is optional.

The alias flags are built into the "alias_flag" table, as follows:

Enabled = 1

KeepEvaluating = 8

IgnoreAliasCase = 32

OmitFromLogFile = 64

RegularExpression = 128

ExpandVariables = 512

Replace = 1024

AliasSpeedWalk = 2048

AliasQueue = 4096

AliasMenu = 8192

Temporary = 16384

Jscript example

world.AddAlias("food_alias", "eat", "eat food", eEnabled, "");

PerlScript example

$world->AddAlias("food_alias", "eat", "eat food", $eEnabled, "");

Python example

world.AddAlias("food_alias", "eat", "eat food", eEnabled, "")

VBscript example

world.addalias "food_alias", "eat", "eat food", eEnabled, ""

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 ImportXML (Imports configuration data in XML format)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=AddAlias)


AddFont

Script function

world.AddFont

 Read about scripting

Type

Method

Summary

Adds a custom font for use by MUSHclient

Prototype

long AddFont(BSTR PathName);

 View list of data type meanings

Description

This adds a font (specified by pathname) into the MUSHclient application space. It can then be used by world windows for output or command window fonts.

Any number of extra fonts can be added per world. (This feature added in version 4.93 of MUSHclient. Prior to version 4.93 you could only add one extra font at a time).

The intention here is for specialized fonts (like mapping fonts) to be made available without having to add extra font files to the Windows directory.

This is only supported on Windows 2000 or later (eg. Windows XP, Vista). It is not supported under Windows 95/98/ME. Use GetInfo (265) through to GetInfo (268) to find which version of Windows you are running under. (Basically GetInfo (265) needs to return 5 or higher).

The file name can specify any of the following files.

.fon	Font resource file.

.fnt	Raw bitmap font file.

.ttf	Raw TrueType file.

.ttc	East Asian Windows: TrueType font collection.

.fot	TrueType resource file.

.otf	PostScript OpenType font.

.mmm	multiple master Type1 font resource file.

It must be used with .pfm and .pfb files.

.pfb	Type 1 font bits file.

It is used with a .pfm file.

.pfm	Type 1 font metrics file.

It is used with a .pfb file.

To add a font whose information comes from several resource files, point lpszFileName to a string with the file names separated by a | --for example, abcxxxxx.pfm | abcxxxxx.pfb.

Return value

eBadParameter - empty file name given

eNoSuchCommand - not supported on your version of Windows

eFileNotFound - file not found, or Windows rejected it as a font file

eOK - added OK

 View list of return code meanings

Lua example

AddFont ("myextrafont.ttf")

VBscript example

AddFont "myextrafont.ttf"

See Also ...

Topics

 Scripting

 Utilities

Functions

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=AddFont)


AddMapperComment

Script function

world.AddMapperComment

 Read about scripting

Type

Method

Summary

Adds a comment to the auto-map sequence

Prototype

long AddMapperComment(BSTR Comment);

 View list of data type meanings

Description

Adds a comment to the auto-map sequence. This lets you put comments into the map sequence (eg. the name of the current room).

Note, mapping does *not* need to be enabled to use this method. This lets you use triggers or aliases to build up a map direction, rather than MUSHclient's automatic mapping.

Return value

eBadMapItem: comment may not contain "{", "}", "(", ")", "/" or "\"

eOK: added OK

 View list of return code meanings

Lua example

AddMapperComment ("Main Square")

Jscript example

world.AddMapperComment ("Main Square");

PerlScript example

$world->AddMapperComment("Main Square");

Python example

world.AddMapperComment ("Main Square")

VBscript example

world.AddMapperComment "Main Square"

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=AddMapperComment)


AddSpellCheckWord

Script function

world.AddSpellCheckWord

 Read about scripting

Type

Method

Summary

Adds a word to the user spell check dictionary

Prototype

long AddSpellCheckWord(BSTR OriginalWord, BSTR ActionCode, BSTR ReplacementWord);

 View list of data type meanings

Description

This lets you add a word to the spell checker "user dictionary" from within a script.

Usage:

result = AddSpellCheckWord (original_word, action, replacement)

original_word = word to match on

action = one of the following single characters (case-sensitive):

'a' = The word should be unconditionally substituted for another word; the substitution should use the case pattern as listed in the lexicon.

'A' = The word should be unconditionally substituted for another word; the substitution should use the case pattern of the original word.

'c' = The word should be conditionally substituted for another word; the substitution should use the case pattern as listed in the lexicon.

'C' = The word should be conditionally substituted for another word; the substitution should use the case pattern of the original word.

'e' = The word should be treated as misspelled by the spell checker, even if it is defined in other lexicons.

'i' = The word should be ignored (skipped) because it is considered correctly spelled.

replacement = the word to replace (or suggest a replacement for) the original word

eg.

AddSpellCheckWord ("foo", "A", "bar")  --> convert "foo" to "bar"

AddSpellCheckWord ("colour", "i", "")  --> "colour" is spelt correctly

Return value

eSpellCheckNotActive - spell checker not enabled or could not be opened

eBadParameter -

original_word not supplied or too long (more than 63 characters); or

replacement word too long (more than 63 characters); or

error returned from spell-check engine

eUnknownOption - action code not in the above list

eOK - did it OK

 View list of return code meanings

Lua example

AddSpellCheckWord ("foo", "A", "bar")  --> convert "foo" to "bar"

AddSpellCheckWord ("colour", "i", "")  --> "colour" is spelt correctly

Lua notes

The third argument (replacement word) is optional and defaults to an empty string.

VBscript example

AddSpellCheckWord "foo", "A", "bar"  ' convert "foo" to "bar"

AddSpellCheckWord "colour", "i", ""  ' "colour" is spelt correctly

See Also ...

Topic

 Spell checker

Functions

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: function=AddSpellCheckWord)


AddTimer

Script function

world.AddTimer

 Read about scripting

Type

Method

Summary

Adds a timer

Prototype

long AddTimer(BSTR TimerName, short Hour, short Minute, double Second, BSTR ResponseText, long Flags, BSTR ScriptName);

 View list of data type meanings

Description

Adds a timer to the list of timers.

Timers can be used to cause something to happen periodically, either every x seconds, or at a certain time of day.

Periodical timers (which fire after a certain time has elapsed) are intended for periodical events (eg. save your world file every hour, drink a potion every minute, check your health every 10 seconds).

Timers that fire at a certain time of day are intended to do things like start a new log file at midnight, warn you if when it is time to go to work, that sort of thing. :)

You can make a "one-shot" timer that does something once, and then deletes itself. This is useful for making a single thing happen in the future (eg. in 5 minutes) rather than happening every 5 minutes.

You can use "DoAfter", "DoAfterNote", "DoAfterSpeedWalk" or "DoAfterSpecial" for a simplified way of adding timers.

TimerName: name of this timer - may be empty (see rules for names below)

Hour: The hour to fire  (0 - 23)

Minute: The minute to fire (0 - 59)

Second: The second to fire (0 - 59.9999)

Response_text: what to send to the world

Flags: various flags, see list below

ScriptName: Which script subroutine to execute

Time Interval

From version 3.61 onwards of MUSHclient the seconds part of the time may include fractions (ie. it is a floating-point number). This lets you set up sub-second timers (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the Timer Interval in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds.

Flags

The flags can be one or more of the constants below. For example, to enable the timer, and make it a one-shot, the flags would be 5. Preferably use the constant declarations in your script file, and "OR" them together. E.g.

VBscript: eEnabled or eOneShot

JScript:  eEnabled | eOneShot

Lua:  timer_flag.Enabled + timer_flag.OneShot

VBscript constants:

const eEnabled = 1   ' is timer enabled?

const eAtTime = 2  ' if not set, time is "every"

const eOneShot = 4  ' if set, timer only fires once

const eTimerSpeedWalk = 8 ' timer does a speed walk when it fires

const eTimerNote = 16 ' timer does a world.note when it fires

const eActiveWhenClosed = 32 ' timer fires even when world is disconnected

const eReplace = 1024  ' replace existing timer of same name

const eTemporary = 16384 ' temporary - do not save to world file

JScript constants:

var eEnabled = 1;   // is timer enabled?

var eAtTime = 2;  // if not set, time is "every"

var eOneShot = 4;   // if set, timer only fires once

var eTimerSpeedWalk = 8; // timer does a speed walk when it fires

var eTimerNote = 16;  // timer does a world.note when it fires

var eActiveWhenClosed = 32;  // timer fires even when world is disconnected

var eReplace = 1024;  // replace existing timer of same name

var eTemporary = 16384; // temporary - do not save to world file

PerlScript constants:

my $eEnabled = 1;   # is timer enabled?

my $eAtTime = 2;   # if not set, time is "every"

my $eOneShot = 4;   # if set, timer only fires once

my $eTimerSpeedWalk = 8; # timer does a speed walk when it fires

my $eTimerNote = 16; # timer does a world.note when it fires

my $eActiveWhenClosed = 32;  # timer fires even when world is disconnected

my $eReplace = 1024;  #  replace existing timer of same name

my $eTemporary = 16384;  # temporary - do not save to world file

Lua constants (in the timer_flag table):

timer_flag.Enabled = 1

timer_flag.AtTime = 2

timer_flag.OneShot = 4

timer_flag.TimerSpeedWalk = 8

timer_flag.TimerNote = 16

timer_flag.ActiveWhenClosed = 32

timer_flag.Replace = 1024

timer_flag.Temporary = 16384

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerAlreadyExists: A timer of that name already exists

eScriptNameNotLocated: The script name cannot be located in the script file

eTimeInvalid: The time is invalid (eg. hour not in range 0 to 23).

eOK: added OK

 View list of return code meanings

Lua example

AddTimer ("my_timer", 0, 0, 1.5, "go north",

          timer_flag.Enabled + timer_flag.OneShot, "")

Lua notes

The script name is optional.

The timer flags are built into the "timer_flag" table, as follows:

Enabled = 1

AtTime = 2

OneShot = 4

TimerSpeedWalk = 8

TimerNote = 16

ActiveWhenClosed = 32

Replace = 1024

Temporary = 16384

Jscript example

world.addtimer("my_timer", 0, 0, 1, "go north", 5, "");

PerlScript example

$world->addtimer("my_timer", 0, 0, 1, "go north", 5, "");

Python example

world.addtimer("my_timer", 0, 0, 1, "go north", 5, "")

VBscript example

world.addtimer "my_timer", 0, 0, 1, "go north", 5, ""

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 ImportXML (Imports configuration data in XML format)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=AddTimer)


AddToMapper

Script function

world.AddToMapper

 Read about scripting

Type

Method

Summary

Adds a mapping direction to the auto-map sequence

Prototype

long AddToMapper(BSTR Direction, BSTR Reverse);

 View list of data type meanings

Description

Adds a new direction to the auto-map sequence. You specify both the forward direction, and the reverse direction (the one taken when going backwards).

For example if you are going North, then the reverse direction is (usually) South.

Note, mapping does *not* need to be enabled to use this method. This lets you use triggers or aliases to build up a map direction, rather than MUSHclient's automatic mapping.

Return value

eBadMapItem: direction (or reverse direction) may not contain "{", "}", "(", ")", "/" or ""

eBadMapItem: forward and reverse direction cannot both be empty

eOK: added OK

 View list of return code meanings

Lua example

AddToMapper("north", "south")

AddToMapper("enter", "leave")

Lua notes

The reverse direction is optional.

Jscript example

world.AddToMapper("north", "south");

world.AddToMapper("enter", "leave");

PerlScript example

$world->AddToMapper("north", "south");

$world->AddToMapper("enter", "leave");

Python example

world.AddToMapper("north", "south")

world.AddToMapper("enter", "leave")

VBscript example

world.AddToMapper "north", "south"

world.AddToMapper "enter", "leave"

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=AddToMapper)


AddTrigger

Script function

world.AddTrigger

 Read about scripting

Type

Method

Summary

Adds a trigger

Prototype

long AddTrigger(BSTR TriggerName, BSTR MatchText, BSTR ResponseText, long Flags, short Colour, short Wildcard, BSTR SoundFileName, BSTR ScriptName);

 View list of data type meanings

Description

Adds a trigger to the list of triggers. If you want to specify the sequence number of the trigger, or where the response text is to be sent to, use AddTriggerEx.

For AddTrigger they default to:

  Sequence: 100

  Send to:  world

Name: name of this trigger - may be empty (see rules for names below)

Match_text: what to match on

Response_text: what to send back to the world

Flags: various flags, see list below

Colour: what colour to draw triggered text, see list below

Wildcard: Copy which wildcard to the clipboard (0 = none), otherwise 1 to 10.

SoundFileName: Which sound file to play

ScriptName: Which script subroutine to execute

Flags

The flags can be one or more of the constants below. For example, to omit from log and omit from output, the flags would be 6. Preferably use the constant declarations in your script file, and "OR" them together. E.g.

VBscript: eOmitFromLog or eOmitFromOutput

JScript: eOmitFromLog | eOmitFromOutput

VBscript:

const eEnabled = 1  ' enable trigger

const eOmitFromLog = 2  ' omit from log file

const eOmitFromOutput = 4  ' omit trigger from output

const eKeepEvaluating = 8  ' keep evaluating

const eIgnoreCase = 16  ' ignore case when matching

const eTriggerRegularExpression = 32  ' trigger uses regular expression

const eExpandVariables = 512  '  expand variables like @direction

const eReplace = 1024  ' replace existing trigger of same name

const eTemporary = 16384 ' temporary - do not save to world file

const eTriggerOneShot = 32768 ' one shot - delete after firing

JScript:

var eEnabled = 1;  //  enable trigger

var eOmitFromLog = 2; // omit from log file

var eOmitFromOutput = 4;  // omit trigger from output

var eKeepEvaluating = 8;  //  keep evaluating

var eIgnoreCase = 16;  //  ignore case when matching

var eTriggerRegularExpression = 32;  //  trigger uses regular expression

var eExpandVariables = 512;  // expand variables like @direction

var eReplace = 1024;  // replace existing trigger of same name

var eTemporary = 16384; // temporary - do not save to world file

var eTriggerOneShot = 32768; // one shot - delete after firing

PerlScript constants:

my $eEnabled = 1;  #  enable trigger

my $eOmitFromLog = 2; # omit from log file

my $eOmitFromOutput = 4;  # omit trigger from output

my $eKeepEvaluating = 8;  #  keep evaluating

my $eIgnoreCase = 16;  #  ignore case when matching

my $eTriggerRegularExpression = 32;  #  trigger uses regular expression

my $eExpandVariables = 512;  # expand variables like @direction

my $eReplace = 1024;  # replace existing trigger of same name

my $eTemporary = 16384;  # temporary - do not save to world file

my $eTriggerOneShot = 32768; # one shot - delete after firing

Colours

VBscript:

const NOCHANGE = -1

const custom1 = 0

const custom2 = 1

const custom3 = 2

const custom4 = 3

const custom5 = 4

const custom6 = 5

const custom7 = 6

const custom8 = 7

const custom9 = 8

const custom10 = 9

const custom11 = 10

const custom12 = 11

const custom13 = 12

const custom14 = 13

const custom15 = 14

const custom16 = 15

JScript:

var NOCHANGE = -1;

var custom1 = 0;

var custom2 = 1;

var custom3 = 2;

var custom4 = 3;

var custom5 = 4;

var custom6 = 5;

var custom7 = 6;

var custom8 = 7;

var custom9 = 8;

var custom10 = 9;

var custom11 = 10;

var custom12 = 11;

var custom13 = 12;

var custom14 = 13;

var custom15 = 14;

var custom16 = 15;

PerlScript:

my $NOCHANGE = -1;

my $custom1 = 0;

my $custom2 = 1;

my $custom3 = 2;

my $custom4 = 3;

my $custom5 = 4;

my $custom6 = 5;

my $custom7 = 6;

my $custom8 = 7;

my $custom9 = 8;

my $custom10 = 9;

my $custom11 = 10;

my $custom12 = 11;

my $custom13 = 12;

my $custom14 = 13;

my $custom15 = 14;

my $custom16 = 15;

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerAlreadyExists: A trigger of that name already exists

eTriggerCannotBeEmpty: The "match_text" cannot be empty

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

eOK: added OK

 View list of return code meanings

Lua example

AddTrigger("monster", "* attacks", "flee", trigger_flag.Enabled , custom_colour.Custom15, 0, "", "")

Lua notes

The script name is optional.

The trigger flags are built into the "trigger_flag" table, as follows:

Enabled = 1

OmitFromLog = 2

OmitFromOutput = 4

KeepEvaluating = 8

IgnoreCase = 16

RegularExpression = 32

ExpandVariables = 512

Replace = 1024

Temporary = 16384

LowercaseWildcard = 2048

OneShot = 32768

The colour names for custom colours are built into the "custom_colour" table, as follows:

NoChange = -1

Custom1 = 0

Custom2 = 1

Custom3 = 2

Custom4 = 3

Custom5 = 4

Custom6 = 5

Custom7 = 6

Custom8 = 7

Custom9 = 8

Custom10 = 9

Custom11 = 10

Custom12 = 11

Custom13 = 12

Custom14 = 13

Custom15 = 14

Custom16 = 15

CustomOther = 16

Jscript example

world.AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "");

PerlScript example

$world->AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "");

Python example

world.AddTrigger("monster", "* attacks", "flee", 1, 14, 0, "", "")

VBscript example

world.addtrigger "monster", "* attacks", "flee", 1, 14, 0, "", ""

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 ImportXML (Imports configuration data in XML format)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=AddTrigger)


AddTriggerEx

Script function

world.AddTriggerEx

 Read about scripting

Type

Method

Summary

Adds a trigger - extended arguments

Prototype

long AddTriggerEx(BSTR TriggerName, BSTR MatchText, BSTR ResponseText, long Flags, short Colour, short Wildcard, BSTR SoundFileName, BSTR ScriptName, short SendTo, short Sequence);

 View list of data type meanings

Description

Adds a trigger to the list of triggers. If you are prepared to accept the default values for Sequence and "Send To" you can use AddTrigger instead.

For AddTrigger they default to:

Sequence: 100

Send to: world

Name: name of this trigger - may be empty  (see rules for names below)

Match_text: what to match on

Response_text: what to send back to the world

Flags: various flags, see list below

Colour: what colour to draw triggered text, see list below

Wildcard: Copy which wildcard to the clipboard (0 = none), otherwise 1 to 10.

SoundFileName: Which sound file to play

ScriptName: Which script subroutine to execute

Sequence: Sequence number of trigger (lower is evaluated earlier). Must be in range 0 to 10,000

Send To: Where to send the trigger text to ...

0: World

1: Command window

2: Output window

3: Status line

4: Notepad (new)

5: Notepad (append)

6: Log File

7: Notepad (replace)

8: Command queue

9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit (send to script engine, after lines have been omitted)

Flags

The flags can be one or more of the constants below. For example, to omit from log and omit from output, the flags would be 6. Preferably use the constant declarations in your script file, and "OR" them together. E.g.

VBscript: eOmitFromLog or eOmitFromOutput

JScript: eOmitFromLog | eOmitFromOutput

VBscript:

const eEnabled = 1 ' enable trigger

const eOmitFromLog = 2 ' omit from log file

const eOmitFromOutput = 4 ' omit trigger from output

const eKeepEvaluating = 8 ' keep evaluating

const eIgnoreCase = 16 ' ignore case when matching

const eTriggerRegularExpression = 32 ' trigger uses regular expression

const eExpandVariables = 512 ' expand variables like @direction

const eReplace = 1024 ' replace existing trigger of same name

const eTemporary = 16384 ' temporary - do not save to world file

JScript:

var eEnabled = 1; // enable trigger

var eOmitFromLog = 2; // omit from log file

var eOmitFromOutput = 4; // omit trigger from output

var eKeepEvaluating = 8; // keep evaluating

var eIgnoreCase = 16; // ignore case when matching

var eTriggerRegularExpression = 32; // trigger uses regular expression

var eExpandVariables = 512; // expand variables like @direction

var eReplace = 1024; // replace existing trigger of same name

var eTemporary = 16384; // temporary - do not save to world file

PerlScript constants:

$eEnabled = 1; # enable trigger

$eOmitFromLog = 2; # omit from log file

$eOmitFromOutput = 4; # omit trigger from output

$eKeepEvaluating = 8; # keep evaluating

$eIgnoreCase = 16; # ignore case when matching

$eTriggerRegularExpression = 32; # trigger uses regular expression

$eExpandVariables = 512; # expand variables like @direction

$eReplace = 1024; # replace existing trigger of same name

$eTemporary = 16384; # temporary - do not save to world file

Colours

VBscript:

const NOCHANGE = -1

const custom1 = 0

const custom2 = 1

const custom3 = 2

const custom4 = 3

const custom5 = 4

const custom6 = 5

const custom7 = 6

const custom8 = 7

const custom9 = 8

const custom10 = 9

const custom11 = 10

const custom12 = 11

const custom13 = 12

const custom14 = 13

const custom15 = 14

const custom16 = 15

JScript:

var NOCHANGE = -1;

var custom1 = 0;

var custom2 = 1;

var custom3 = 2;

var custom4 = 3;

var custom5 = 4;

var custom6 = 5;

var custom7 = 6;

var custom8 = 7;

var custom9 = 8;

var custom10 = 9;

var custom11 = 10;

var custom12 = 11;

var custom13 = 12;

var custom14 = 13;

var custom15 = 14;

var custom16 = 15;

PerlScript:

$NOCHANGE = -1;

$custom1 = 0;

$custom2 = 1;

$custom3 = 2;

$custom4 = 3;

$custom5 = 4;

$custom6 = 5;

$custom7 = 6;

$custom8 = 7;

$custom9 = 8;

$custom10 = 9;

$custom11 = 10;

$custom12 = 11;

$custom13 = 12;

$custom14 = 13;

$custom15 = 14;

$custom16 = 15;

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerAlreadyExists: A trigger of that name already exists

eTriggerCannotBeEmpty: The "match_text" cannot be empty

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

eTriggerSequenceOutOfRange: Sequence is not in range 0 to 10000

eTriggerSendToInvalid: Send to field is not in range 0 to 9

eOK: added OK

 View list of return code meanings

Lua example

AddTriggerEx ("", "* attacks", "You are under attack!", trigger_flag.Enabled, custom_colour.Custom15, 0, "", "", 2, 50)

Lua notes

The trigger sequence is optional and defaults to 100.

The trigger flags are built into the "trigger_flag" table, as follows:

trigger_flag.Enabled = 1

trigger_flag.OmitFromLog = 2

trigger_flag.OmitFromOutput = 4

trigger_flag.KeepEvaluating = 8

trigger_flag.IgnoreCase = 16

trigger_flag.RegularExpression = 32

trigger_flag.ExpandVariables = 512

trigger_flag.Replace = 1024

trigger_flag.Temporary = 16384

trigger_flag.LowercaseWildcard = 2048

The colour names for custom colours are built into the "custom_colour" table, as follows:

custom_colour.NoChange = -1

custom_colour.Custom1 = 0

custom_colour.Custom2 = 1

custom_colour.Custom3 = 2

custom_colour.Custom4 = 3

custom_colour.Custom5 = 4

custom_colour.Custom6 = 5

custom_colour.Custom7 = 6

custom_colour.Custom8 = 7

custom_colour.Custom9 = 8

custom_colour.Custom10 = 9

custom_colour.Custom11 = 10

custom_colour.Custom12 = 11

custom_colour.Custom13 = 12

custom_colour.Custom14 = 13

custom_colour.Custom15 = 14

custom_colour.Custom16 = 15

custom_colour.CustomOther = 16

The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

world.AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50);

PerlScript example

$world->AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50);

Python example

world.AddTriggerEx ("", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50)

VBscript example

world.AddTriggerEx "", "* attacks", "You are under attack!", 1, 14, 0, "", "", 2, 50

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 ImportXML (Imports configuration data in XML format)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=AddTriggerEx)


AdjustColour

Script function

world.AdjustColour

 Read about scripting

Type

Method

Summary

Adjust an RGB colour

Prototype

long AdjustColour(long Colour, short Method);

 View list of data type meanings

Description

This lets you play with colours in a script. You pass to it a colour and an adjustment method. The methods are:

1: invert

2: lighter

3: darker

4: less colour

5: more colour

This lets you do in a script what can be done on the ANSI colour page - fiddle with colour values.

Return value

The RGB code of the adjusted colour. If the method is out of range the original colour is returned.

Lua example

mycolour = AdjustColour (ColourNameToRGB ("red"), 1) -- get inverse of red

Jscript example

mycolour = AdjustColour (ColourNameToRGB ("red"), 1); // get inverse of red

PerlScript example

mycolour = AdjustColour (ColourNameToRGB ("red"), 1); # get inverse of red

Python example

mycolour = world.AdjustColour (world.ColourNameToRGB ("red"), 1) # get inverse of red

VBscript example

mycolour = world.AdjustColour (ColourNameToRGB ("red"), 1) ' get inverse of red

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=AdjustColour)


ANSI

Script function

world.ANSI

 Read about scripting

Type

Method

Summary

Generates an ANSI colour sequence

Prototype

BSTR ANSI(short Code);

 View list of data type meanings

Description

This generates an ANSI colour sequence, like this:

ESC [ code m

The code number is supplied as an argument.

This is intended to be used with the ANSINote function - which lets you write to the output window with ANSI formatting, or to send to other clients via the chat system.

Useful numbers to use would be:

Miscellaneous

 0: reset

 1: bold

 3: blink (is rendered as italic)

 4: underline

 7: inverse

22: cancel bold

23: cancel blink

24: cancel underline

27: cancel inverse

Foreground (text) colour

30: Black

31: Red

32: Green

33: Yellow

34: Blue

35: Magenta

36: Cyan

37: White

Background colour

40: Black

41: Red

42: Green

43: Yellow

44: Blue

45: Magenta

46: Cyan

47: White

// 256 colour ANSI foreground

38;5;n  where n is 0 to 255

// 256 colour ANSI background

48;5;n  where n is 0 to 255

Suggestion - you could conceivably replace colours in incoming chat messages by doing a world.Replace using ANSI, providing the incoming ANSI codes conform exactly to the rendering used here.

For example:

  mymessage = world.Replace (incoming_message, ANSI (36), ANSI (37))

This would hopefully replace the code for Cyan with the code for White.

Return value

A string consisting of: ESC "[" Code "m"

Lua example

AnsiNote ("This is normal ",

          ANSI (33, 47),

          "and this is yellow on white")

Lua notes

You can supply multiple arguments, as in the above example.

Each one will generate its own ANSI code, so you can easily do multiple changes

(eg. foreground, background, bold) in a single call to ANSI.

If you supply multiple arguments they will be placed into the same ANSI sequence, like this:

ANSI (33, 47) --> ESC[33;47m

Jscript example

ANSINote ("This is normal" + ANSI (33) + " and this is yellow");

PerlScript example

ANSINote ("This is normal" . ANSI (33) . " and this is yellow");

Python example

world.ANSINote ("This is normal",

world.ANSI (33, 47), " and this is yellow")

VBscript example

ANSINote "This is normal" & ANSI (33) & " and this is yellow"

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNote (Does a note using ANSI codes for the chat system)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 StripANSI (Strips ANSI colour sequences from a string)

(Help topic: function=ANSI)


AnsiNote

Script function

world.AnsiNote

 Read about scripting

Type

Method

Summary

Make a note in the output window from text with ANSI colour codes imbedded

Prototype

void AnsiNote(BSTR Text);

 View list of data type meanings

Description

Sends "Text" to the output window, changing colour, bold, underline etc. if it gets ANSI sequences in the text. ANSI sequences are things like ESC [ 30 m. You can use the ANSI function to set them up.

AnsiNote saves the current world note colour, and restores it afterwards, so that any colour changes do not persist to subsequent note lines.

The ANSI sequences defined in the ANSI function will be recognised.

WARNING: Bold italic, and underlined styles will only be visible if the appropriate configurations are enabled in the world Appearance: Output configuration. Otherwise they will be ignored (the same as for text arriving from the MUD).

Return value

Nothing.

Lua example

AnsiNote (ANSI (32, 1, 43),

          "This is bold green text on a yellow background")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

AnsiNote (ANSI (32) + ANSI (1) + ANSI (43) +

         "This is bold green text on a yellow background");

PerlScript example

AnsiNote (ANSI (32) . ANSI (1) . ANSI (43) .

         "This is bold green text on a yellow background");

Python example

world.AnsiNote (world.ANSI (32) + world.ANSI (1) + world.ANSI (43) +

"This is bold green text on a yellow background")

VBscript example

AnsiNote ANSI (32) & ANSI (1) & ANSI (43) & _

          "This is bold green text on a yellow background"

See Also ...

Topic

 Notes

Functions

 ANSI (Generates an ANSI colour sequence)

 ChatNote (Does a note using ANSI codes for the chat system)

 ColourNote (Sends a message to the output window in specified colours)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 SetNotes (Sets the notes for the world.)

 StripANSI (Strips ANSI colour sequences from a string)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=AnsiNote)


AppendToNotepad

Script function

world.AppendToNotepad

 Read about scripting

Type

Method

Summary

Appends text to a notepad window

Prototype

boolean AppendToNotepad(BSTR Title, BSTR Contents);

 View list of data type meanings

Description

Appends the text to a notepad window of the given title. If no such window exists, it is created.

The function "AppendToNotepad" does not activate (bring to the front) the notepad window. However the function "ActivateNotepad" can be used to do that.

You can use world.activate to activate the world itself (eg. you might want to do that after creating a notepad window).

You might use GetNotepadLength to check if there is likely to be room in the notepad for the new text.

Return value

0: Could not do it.

1:  Appended OK

Lua example

AppendToNotepad("Nick's window", "More stuff\r\n",

                "another line")

Lua notes

You can supply multiple arguments after the notepad name, which are concatenated together.

Jscript example

world.AppendToNotepad("Nick's window", "More stuff\r\n");

PerlScript example

$world->AppendToNotepad("Nick's window", "More stuff\r\n");

Python example

world.AppendToNotepad("Nick's window", "More stuff\r\n")

VBscript example

world.AppendToNotepad "Nick's window", "More stuff" + vbcrlf

See Also ...

Topic

 Notepad

Functions

 Activate (Activates the world window)

 ActivateNotepad (Activates a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=AppendToNotepad)


ArrayClear

Script function

world.ArrayClear

 Read about scripting

Type

Method

Summary

Clears an array

Prototype

long ArrayClear(BSTR Name);

 View list of data type meanings

Description

This removes all values from the array, effectively making it empty.

Return value

eBadArrayName: Name cannot be empty

eArrayDoesNotExist: Array does not exist

eOK: Cleared OK

 View list of return code meanings

Lua example

ArrayClear "spells"

VBscript example

ArrayClear "spells"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayClear)


ArrayCount

Script function

world.ArrayCount

 Read about scripting

Type

Method

Summary

Returns the number of arrays

Prototype

long ArrayCount();

 View list of data type meanings

Description

This returns the number of arrays in the current world (or current plugin, if executed from a plugin).

Return value

The number of arrays in the current world, or the current plugin, which may be zero.

Lua example

Note ("count of arrays = " .. ArrayCount ())

VBscript example

Note "count of arrays = " & ArrayCount

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayCount)


ArrayCreate

Script function

world.ArrayCreate

 Read about scripting

Type

Method

Summary

Creates an array

Prototype

long ArrayCreate(BSTR Name);

 View list of data type meanings

Description

This creates an array for use by scripting. The array name may consist of any characters (except the "null" character, hex 00), and is case-sensitive.

The array must be created before it is used.

Return value

eBadArrayName: Name cannot be empty

eArrayAlreadyExists: Array already exists

eOK: Created OK

 View list of return code meanings

Lua example

ArrayCreate "spells"

VBscript example

ArrayCreate "spells"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayCreate)


ArrayDelete

Script function

world.ArrayDelete

 Read about scripting

Type

Method

Summary

Deletes an array

Prototype

long ArrayDelete(BSTR Name);

 View list of data type meanings

Description

This deletes a previously-created arrays. All values are discarded. Arrays are automatically deleted when the world is closed, or the plugin closed if the array is in a plugin.

Return value

eBadArrayName: Name cannot be empty

eArrayDoesNotExist: Array does not exist

eOK: Deleted OK

 View list of return code meanings

Lua example

ArrayDelete "spells"

VBscript example

ArrayDelete "spells"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayDelete)


ArrayDeleteKey

Script function

world.ArrayDeleteKey

 Read about scripting

Type

Method

Summary

Deletes a key/value pair from an array

Prototype

long ArrayDeleteKey(BSTR Name, BSTR Key);

 View list of data type meanings

Description

This deletes a key/value pair from an array. You specify which key to delete, and if it exists in the array, it is deleted.

Return value

eBadArrayName: Name cannot be empty

eBadKeyName: Key cannot be empty

eArrayDoesNotExist: Array does not exist

eKeyDoesNotExist: Key does not exist

eOK: Deleted OK

 View list of return code meanings

Lua example

ArrayDeleteKey ("spells", "farsight")

VBscript example

ArrayDeleteKey "spells", "farsight"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayDeleteKey)


ArrayExists

Script function

world.ArrayExists

 Read about scripting

Type

Method

Summary

Tests to see if the specified array exists

Prototype

boolean ArrayExists(BSTR Name);

 View list of data type meanings

Description

This returns TRUE (1) if the specified array exists, and FALSE (0) if it does not.

Return value

TRUE if the array exists.

FALSE if it does not exist.

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note (ArrayExists ("spells"))

VBscript example

Note ArrayExists ("spells")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayExists)


ArrayExport

Script function

world.ArrayExport

 Read about scripting

Type

Method

Summary

Exports values from an array into a single string

Prototype

VARIANT ArrayExport(BSTR Name, BSTR Delimiter);

 View list of data type meanings

Description

Exports key/value pairs from the nominated array.

They keys and values will be separated by the specified delimiter, for example:

dispel magic,15,dragonskin,45,farsight,15,galvanic whip,30

The first word is the key (eg. dispel magic) the second word is the value (eg. 15) and so on, until the list of keys/values is exhausted.

The list may be the empty string, which indicates that the array had no values.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. The delimiter must be a single character (eg. ",") other than the backslash character. If the keys, or the values, contain the delimiter they will be "escaped", for example if the delimiter is a comma then any commas will be exported as backslash-comma.  (ie. "," becomes ","). Also, any backslashes are exported as double-backslashes. (eg. "" becomes "").

If you just want the key names and not the values, use ArrayExportKeys.

Return value

If successful, the return value is a string containing the key/value pairs for the specified array, separated by the delimiter.

If not successful, the return value is a number (type 'long') with one of the following error codes in it:

eBadArrayName: Name cannot be empty

eArrayDoesNotExist: Array does not exist

eBadDelimiter: The delimiter is not a single character, or is the backslash character

Lua example

SetVariable ("spells", ArrayExport ("spells", ","))

Lua notes

The delimiter is optional, and defaults to the "," character.

VBscript example

SetVariable "spells", ArrayExport ("spells", ",")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayExport)


ArrayExportKeys

Script function

world.ArrayExportKeys

 Read about scripting

Type

Method

Summary

Exports keys from an array into a single string

Prototype

VARIANT ArrayExportKeys(BSTR Name, BSTR Delimiter);

 View list of data type meanings

Description

Exports keys from the nominated array.

They keys will be separated by the specified delimiter, for example:

dispel magic,dragonskin,farsight,galvanic whip

The list may be the empty string, which indicates that the array had no values.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. The delimiter must be a single character (eg. ",") other than the backslash character. If the keys contain the delimiter they will be "escaped", for example if the delimiter is a comma then any commas will be exported as backslash-comma.  (ie. "," becomes ","). Also, any backslashes are exported as double-backslashes. (eg. "" becomes "").

If you want the key values as well as the names, use ArrayExport.

Return value

If successful, the return value is a string containing the keys for the specified array, separated by the delimiter.

If not successful, the return value is a number (type 'long') with one of the following error codes in it:

eBadArrayName: Name cannot be empty

eArrayDoesNotExist: Array does not exist

eBadDelimiter: The delimiter was not a single character, or was the backslash character

Lua example

Note (ArrayExportKeys ("spells", ","))

Lua notes

The delimiter is optional, and defaults to the "," character.

VBscript example

Note ArrayExportKeys ("spells", ",")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayExportKeys)


ArrayGet

Script function

world.ArrayGet

 Read about scripting

Type

Method

Summary

Gets the value of an array item

Prototype

VARIANT ArrayGet(BSTR Name, BSTR Key);

 View list of data type meanings

Description

This retrieves the value for a specified key, for a specified array.

Return value

The value for the specified key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name

* Bad key name

* Array does not exist

* Key does not exist

Lua example

Note (ArrayGet ("spells", "galvanic whip"))

Lua notes

Lua returns nil where applicable instead of an "empty variant".

VBscript example

Note ArrayGet ("spells", "galvanic whip")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayGet)


ArrayGetFirstKey

Script function

world.ArrayGetFirstKey

 Read about scripting

Type

Method

Summary

Gets the key of the first element in the array (if any)

Prototype

VARIANT ArrayGetFirstKey(BSTR Name);

 View list of data type meanings

Description

This retrieves the key of the first element in a specified array. You can then use ArrayGet to get the value associated with that key.

The first element is the one with the lowest key, not the one that was inserted first.

You could use this to implement a queue (to pull out the first entry in the queue).

Return value

The value of the first key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name

* Array does not exist

* Array is empty

Lua example

Note (ArrayGetFirstKey ("spells"))

Lua notes

Lua returns nil where applicable instead of an "empty variant".

VBscript example

Note ArrayGetFirstKey ("spells")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayGetFirstKey)


ArrayGetLastKey

Script function

world.ArrayGetLastKey

 Read about scripting

Type

Method

Summary

Gets the key of the last element in the array (if any)

Prototype

VARIANT ArrayGetLastKey(BSTR Name);

 View list of data type meanings

Description

This retrieves the key of the last element in a specified array. You can then use ArrayGet to get the value associated with that key.

You could use this to implement a stack (to pull out the last entry in the stack).

Return value

The value of the last key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name

* Array does not exist

* Array is empty

Lua example

Note (ArrayGetLastKey ("spells"))

Lua notes

Lua returns nil where applicable instead of an "empty variant".

VBscript example

Note ArrayGetLastKey ("spells")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayGetLastKey)


ArrayImport

Script function

world.ArrayImport

 Read about scripting

Type

Method

Summary

Imports values into an array from a single string

Prototype

long ArrayImport(BSTR Name, BSTR Values, BSTR Delimiter);

 View list of data type meanings

Description

Imports key/value pairs into the nominated array.

They keys and values must be separated by the specified delimiter, for example:

dispel magic,15,dragonskin,45,farsight,15,galvanic whip,30

The first word is the key (eg. dispel magic) the second word is the value (eg. 15) and so on, until the list of keys/values is exhausted.

It is an error if the number of keys/values is not even (that is, there should be one value for each key).

The list may be the empty string, in which case nothing is imported.

You may import on top of an existing array (ie. add to it). The new values are slotted in with the existing values. If the new values have the same key as existing values the existing values are overwritten. The return value from this function tells you if this happens.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. If you want to use the delimiter inside the key or value data, then you must precede it (escape it) with a backslash. Also, if you want to have backslashes in the keys or values, use a double-backslash.

Return value

eBadArrayName: Name cannot be empty

eArrayDoesNotExist: Array does not exist

eArrayNotEvenNumberOfValues: There is not an even number of keys/values

eImportedWithDuplicates: Imported successfully, however there were duplicates which were overwritten

eCannotImport: The data to be imported contains the "escaped delimiter" sequence, and there is no unused character (eg. hex 01) to temporarily convert it to internally for importing purposes.

eOK: Imported OK

 View list of return code meanings

Lua example

ArrayImport ("spells", "dispel magic,15,dragonskin,45,galvanic whip,30", ",")

Lua notes

The delimiter is optional, and defaults to the "," character.

As an optional extension you can supply a Lua table as the second argument,

instead of a delimited string. (In this case there is no third argument).

eg.

t = {

    ['dispel magic'] = 15,

    dragonskin = 45,

    ['galvanic whip'] = 30

    }

ArrayImport ("spells", t)

This effectively lets you import into Lua tables with ArrayImport, and then

export later on with ArrayList.

VBscript example

ArrayImport "spells", "dispel magic,15,dragonskin,45,galvanic whip,30", ","

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayImport)


ArrayKeyExists

Script function

world.ArrayKeyExists

 Read about scripting

Type

Method

Summary

Tests to see if the specified array key exists

Prototype

boolean ArrayKeyExists(BSTR Name, BSTR Key);

 View list of data type meanings

Description

This returns TRUE (1) if the specified key in the specified array exists, and FALSE (0) if it does not.

Return value

TRUE if the key in the array exists.

FALSE if it does not exist.

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note (ArrayKeyExists ("spells", "farsight"))

VBscript example

Note ArrayKeyExists ("spells", "farsight")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayKeyExists)


ArrayListAll

Script function

world.ArrayListAll

 Read about scripting

Type

Method

Summary

Gets the list of arrays

Prototype

VARIANT ArrayListAll();

 View list of data type meanings

Description

Returns an array of all the arrays currently defined.

Return value

If there are no arrays then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the arrays.

Use "lbound" and "ubound" to find the bounds of the array of arrays (ie. the number of arrays in the list). You can then use "ArrayListKeys" to find the keys for each array.

Lua example

for k, v in pairs (ArrayListAll ()) do

  Note (v)

end

VBscript example

dim arrList

arrList = world.ArrayListAll

If Not IsEmpty (arrList) Then

  For Each a In arrList

    world.note a

  Next

End If

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayListAll)


ArrayListKeys

Script function

world.ArrayListKeys

 Read about scripting

Type

Method

Summary

Gets the list of all the keys in an array

Prototype

VARIANT ArrayListKeys(BSTR Name);

 View list of data type meanings

Description

Returns an array of all the keys in the nominated array. You could use this to then examine the value for each key (using ArrayGet).

You can also use ArrayListValues if all you are interested in is the values but not the keys they belong to.

Return value

If there are no elements in the nominated array then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the keys in this array.

Use "lbound" and "ubound" to find the bounds of the array of keys (ie. the number of keys in the list). You can then use "ArrayGet" to find the values for each key.

Lua example

for k, v in pairs (ArrayListKeys ("spells")) do

  Note (v)

end

-- alternative - show keys and values:

table.foreach (ArrayList ("spells"), print)

-- show a particular value:

spells = ArrayList ("spells")

print (spells.dragonskin)

Lua notes

If the array does not exist, or is empty, Lua returns nil.

There is an extension for Lua only - ArrayList - which returns both keys and values.

See above example. The key of the table is the array key, the value is the array value.

VBscript example

dim keyList

keyList = ArrayListKeys ("spells")

If Not IsEmpty (keyList) Then

  For Each k In keyList

    world.note k & " = " & ArrayGet ("spells", k)

  Next

End If

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayListKeys)


ArrayListValues

Script function

world.ArrayListValues

 Read about scripting

Type

Method

Summary

Gets the list of all the values in an array

Prototype

VARIANT ArrayListValues(BSTR Name);

 View list of data type meanings

Description

Returns an array of all the values in the nominated array. That is, the values for each entry but not the keys.

You can also use ArrayListKeys if you want to find the keys instead.

Return value

If there are no elements in the nominated array then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing all of the values in this array.

Use "lbound" and "ubound" to find the bounds of the array of values (ie. the number of values in the list).

Lua example

for k, v in pairs (ArrayListValues ("spells")) do

  Note (v)

end

-- alternative - show keys and values:

table.foreach (ArrayList ("spells"), print)

-- show a particular value:

spells = ArrayList ("spells")

print (spells.dragonskin)

Lua notes

If the array does not exist, or is empty, Lua returns nil.

There is an extension for Lua only - ArrayList - which returns both keys and values.

See above example. The key of the table is the array key, the value is the array value.

VBscript example

dim valList

valList = ArrayListValues ("spells")

If Not IsEmpty (valList) Then

  For Each v In valList

    world.note v

  Next

End If

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArraySet (Sets the value of an array item)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArrayListValues)


ArraySet

Script function

world.ArraySet

 Read about scripting

Type

Method

Summary

Sets the value of an array item

Prototype

long ArraySet(BSTR Name, BSTR Key, BSTR Value);

 View list of data type meanings

Description

This sets the value for a specified key, for a specified array.

Return value

eBadArrayName: Name cannot be empty

eBadKeyName: Key cannot be empty

eArrayDoesNotExist: Array does not exist

eSetReplacingExistingValue: Value set, however it overwrote an existing value

eOK: Set OK

 View list of return code meanings

Lua example

ArraySet ("spells", "dragonskin", "45")

VBscript example

ArraySet "spells", "dragonskin", "45"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySize (Returns the number of elements in a specified array)

(Help topic: function=ArraySet)


ArraySize

Script function

world.ArraySize

 Read about scripting

Type

Method

Summary

Returns the number of elements in a specified array

Prototype

long ArraySize(BSTR Name);

 View list of data type meanings

Description

This returns the number of elements in the specified array.

Return value

The number of elements in the specified array, which may be zero.

Lua example

Note ("items in spells array = " .. ArraySize ("spells"))

VBscript example

Note "items in spells array = " & ArraySize ("spells")

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 ArrayClear (Clears an array)

 ArrayCount (Returns the number of arrays)

 ArrayCreate (Creates an array)

 ArrayDelete (Deletes an array)

 ArrayDeleteKey (Deletes a key/value pair from an array)

 ArrayExists (Tests to see if the specified array exists)

 ArrayExport (Exports values from an array into a single string)

 ArrayExportKeys (Exports keys from an array into a single string)

 ArrayGet (Gets the value of an array item)

 ArrayGetFirstKey (Gets the key of the first element in the array (if any))

 ArrayGetLastKey (Gets the key of the last element in the array (if any))

 ArrayImport (Imports values into an array from a single string)

 ArrayKeyExists (Tests to see if the specified array key exists)

 ArrayListAll (Gets the list of arrays)

 ArrayListKeys (Gets the list of all the keys in an array)

 ArrayListValues (Gets the list of all the values in an array)

 ArraySet (Sets the value of an array item)

(Help topic: function=ArraySize)


Base64Decode

Script function

world.Base64Decode

 Read about scripting

Type

Method

Summary

Takes a base-64 encoded string and decodes it.

Prototype

VARIANT Base64Decode(BSTR Text);

 View list of data type meanings

Description

Takes a base-64 encoded string (eg. "TmljayBHYW1tb24=") and decodes it. The string may contain space characters (including carriage-return/newline) which will be removed.

The string to be decoded must contain valid base-64 characters, and must be a multiple of 4 characters long (once spaces are removed), or a NULL variant will be returned.

The valid base-64 characters are:

'A','B','C','D','E','F','G','H','I','J','K','L','M','N','O','P',

'Q','R','S','T','U','V','W','X','Y','Z','a','b','c','d','e','f',

'g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v',

'w','x','y','z','0','1','2','3','4','5','6','7','8','9','+','/'

Also, '=' is used as a padding character if the original text to be encoded was not exactly a multiple of 3 characters long.

Because of the way strings are stored this will not work with strings which have nulls in them (hex 00), however see below for a work-around for Lua.

Return value

The decoded string, or a NULL variant if the input string was not a multiple of 4 characters in length, once spaces were removed, or did not contain the valid base-64 characters listed above.

Note that due to the way strings are represented internally, it is not possible for the decoded string to contain the NULL character (hex 0x00) and be returned correctly.

Lua example

Note (Base64Decode ("TmljayBHYW1tb24="))

-- or, as described in the notes:

Note (utils.base64decode ("TmljayBHYW1tb24="))

Lua notes

In MUSHclient version 3.57 onwards you can also use

decoded_string = utils.base64decode (s)

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.

This function works a bit differently if it encounters "bad" data:

* Characters not in the set shown above are silently ignored

* If the source string is not a multiple of four characters, the string is still processed, however up to the last 3 bytes will not be returned.

Jscript example

world.note (world.Base64Decode ("TmljayBHYW1tb24="));

PerlScript example

$world->note ($world->Base64Decode ("TmljayBHYW1tb24="));

Python example

world.note (world.Base64Decode ("TmljayBHYW1tb24="))

VBscript example

world.note world.Base64Decode ("TmljayBHYW1tb24=")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=Base64Decode)


Base64Encode

Script function

world.Base64Encode

 Read about scripting

Type

Method

Summary

Encodes a string using base-64 encoding.

Prototype

VARIANT Base64Encode(BSTR Text, BOOL MultiLine);

 View list of data type meanings

Description

Encodes a string (like "swordfish") returning it as base-64 characters (eg. "c3dvcmRmaXNo").

Each 3 characters of input become 4 characters of output. This can be used:

a) as a primitive form of encryption (or 'information hiding')

b) to send non-printable characters as a text stream

Note that due to the way strings are represented internally, it is not possible for the encoded string to contain the NULL character (hex 0x00) and be returned correctly, however see below for a work-around for Lua.

If "multiline" is true, then the returned string will have a carriage-return/linefeed after every 76 characters, otherwise it will be one long text stream.

Return value

The encoded string.

Lua example

Note (Base64Encode ("swordfish", 0))

Lua notes

The multi-line flag is optional, and defaults to false.

---

In MUSHclient version 3.57 onwards you can also use

encoded_string = utils.base64encode (s, [, linebreaks] )

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.

Jscript example

world.note (world.base64encode ("swordfish", 0));

PerlScript example

$world->note ($world->base64encode ("swordfish", 0));

Python example

world.note (world.base64encode ("swordfish", 0))

VBscript example

world.note world.base64encode ("swordfish", 0)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 Base64Decode (Takes a base-64 encoded string and decodes it.)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=Base64Encode)


BlendPixel

Script function

world.BlendPixel

 Read about scripting

Type

Method

Summary

Blends a single pixel with another, using a specified blending mode

Prototype

long BlendPixel(long Blend, long Base, short Mode, double Opacity);

 View list of data type meanings

Description

This does the same thing as WindowBlendImage, except it operates on a single pixel (that is, a single RGB colour for the blend colour, and a single RGB colour for the base colour). This does the same thing, to a single pixel, as WindowBlendImage (with the same codes). This is intended for situations where you need to work on individual colours - either in a miniwindow image, or generally, to do things like merge them together in various ways.

Blend - the RGB code of the pixel to be blended

Base - the RGB code of the base pixel

Mode - the blending method.

Mode 1 - Normal

Mode 2 - Average

Mode 3 - Interpolate

Mode 4 - Dissolve

Mode 5 - Darken

Mode 6 - Multiply

Mode 7 - Colour Burn

Mode 8 - Linear Burn

Mode 9 - Inverse Colour Burn

Mode 10 - Subtract

Mode 11 - Lighten

Mode 12 - Screen

Mode 13 - Colour Dodge

Mode 14 - Linear Dodge

Mode 15 - Inverse Colour Dodge

Mode 16 - Add

Mode 17 - Overlay

Mode 18 - Soft Light

Mode 19 - Hard Light

Mode 20 - Vivid Light

Mode 21 - Linear Light

Mode 22 - Pin Light

Mode 23 - Hard Mix

Mode 24 - Difference

Mode 25 - Exclusion

Mode 26 - Reflect

Mode 27 - Glow

Mode 28 - Freeze

Mode 29 - Heat

Mode 30 - Negation

Mode 31 - Phoenix

Mode 32 - Stamp

Mode 33 - Xor

Mode 34 - And

Mode 35 - Or

Mode 36 - Red

Mode 37 - Green

Mode 38 - Blue

Mode 39 - Yellow

Mode 40 - Cyan

Mode 41 - Magenta

Mode 42 - Green limited by red

Mode 43 - Green limited by blue

Mode 44 - Green limited by average of red and blue

Mode 45 - Blue limited by red

Mode 46 - Blue limited by green

Mode 47 - Blue limited by average of red and green

Mode 48 - Red limited by green

Mode 49 - Red limited by blue

Mode 50 - Red limited by average of green and blue

Mode 51 - Red only

Mode 52 - Green only

Mode 53 - Blue only

Mode 54 - Discard red

Mode 55 - Discard green

Mode 56 - Discard blue

Mode 57 - All red

Mode 58 - All green

Mode 59 - All blue

Mode 60 - Hue mode

Mode 61 - Saturation mode

Mode 62 - Colour mode

Mode 63 - Luminance mode

Mode 64 - HSL

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means the result will be the base pixel. An opacity of 1 means the blend is fully applied. An opacity of 0.5 means the blended pixel is merged 50% with the original pixel.

For more information and screen shots showing the effects of various modes, see:

http://www.gammon.com.au/mushclient/mw_blending.htm

Return value

-1: The blend mode was not in the above list.

-2: Opacity less than zero or greater than 1.

Otherwise, the RGB code resulting from the blend operation.

Lua example

BlendPixel (0x123456, 0x445566, 1, 0.5) -- mode 1 (normal) at 50% opacity (gives 0x2b445e)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 Base64Decode (Takes a base-64 encoded string and decodes it.)

 Base64Encode (Encodes a string using base-64 encoding.)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

(Help topic: function=BlendPixel)


BoldColour

Script function

world.BoldColour

 Read about scripting

Type

Property

Summary

Gets/sets the RGB colour for one of the 8 ANSI bold colours

Prototype

long BoldColour(short WhichColour);

void BoldColour(short WhichColour, long nNewValue);

 View list of data type meanings

Description

You can use this property to get or set the RGB colours used for the 8 ANSI bold colours. You must specify *which* colour you want to get/set, in the range 1 to 8, as follows:

black = 1

red     = 2

green   = 3

yellow  = 4

blue    = 5

magenta = 6

cyan    = 7

white   = 8

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour.

Return value

This is a property. You can use it to find the current bold colour.

Lua example

Note (GetBoldColour (2))

SetBoldColour (2, 254)

Redraw()   -- redraw screen

Lua notes

Lua implements this as two functions:

GetBoldColour - gets the bold colour

SetBoldColour - sets the bold colour

Jscript example

world.Note(world.boldcolour(2));

world.boldcolour(2) = 0xFF;

world.redraw();   // redraw screen

PerlScript example

$world->Note($world->boldcolour(2));

Python example

world.Note(world.boldcolour(2))

VBscript example

world.note world.boldcolour (2)

world.boldcolour (2) = vbRed

world.redraw   ' redraw screen

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 Redraw (Schedules a redraw for all windows for this world)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=BoldColour)


Bookmark

Script function

world.Bookmark

 Read about scripting

Type

Method

Summary

Sets of clears a bookmark on the nominated line

Prototype

void Bookmark(long LineNumber, BOOL Set);

 View list of data type meanings

Description

Sets or clears a bookmark on any line in the output buffer (window).

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window. This number is different from the sequential number of the line since the world opened.

Note that when the buffer fills up lines are discarded in batches of 100, so the last line will probably not be 5000, even if your buffer size is 5000 and you have been connected for a while. It is likely to be in the range 4900 to 4999.

If the argument "Set" is true a bookmark is set, otherwise it is cleared.

Bookmarks do not consume any extra memory (they are a flag in the existing memory allocated for a line), and you can have as many bookmarks as there are lines. Inside the client the "go to bookmark" menu operation (Ctrl+B) can be used to navigate through bookmarked lines.

Return value

None.

Lua example

-- bookmark the most recently-received line

Bookmark (GetLinesInBufferCount (), true)

Lua notes

The Set argument is optional. If omitted it defaults to true.

See Also ...

Function

 GetLinesInBufferCount (Returns the number of lines in the output window)

(Help topic: function=Bookmark)


BroadcastPlugin

Script function

world.BroadcastPlugin

 Read about scripting

Type

Method

Summary

Broadcasts a message to all installed plugins

Prototype

long BroadcastPlugin(long Message, BSTR Text);

 View list of data type meanings

Description

Broadcasts the message to all installed plugins.

The intention here is for one plugin to catch an event and "notify" all other plugins of that event.

You supply 2 arguments, a number and a string.

The number is intended to be a "message number", to indicate the type of message (eg. trigger has fired = 1, alias matched = 2).

The string is intended to allow you to supply free-format data to the plugin.

All installed plugins are checked for a function OnPluginBroadcast. If present, it is called with 4 arguments:

1 - the message number (supplied above).

2 - the ID of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

3 - the name of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

4 - the Text argument (supplied above)

An example of a plugin handler might be (in Lua):

function OnPluginBroadcast (msg, id, name, text)

  Note ("msg = " .. msg)

  Note ("id = " .. id)

  Note ("name = " .. name)

  Note ("text = " .. text)

end

The calling plugin ID and name are supplied so that plugin writers can verify which plugin originated a particular message. This cannot be spoofed as it is supplied automatically by MUSHclient.

Thus, a sensible test might be for a plugin that incorporates an OnPluginBroadcast handler, to test the id supplied to match the id of the plugin that it expects to be doing the broadcast.

Return value

The number of plugins that had an OnPluginBroadcast handler.

Lua example

BroadcastPlugin (100, "some message")

Lua notes

The Text parameter is optional, and defaults to an empty string.

Jscript example

world.BroadcastPlugin (100, "some message");

PerlScript example

$world->BroadcastPlugin (100, "some message");

Python example

world.BroadcastPlugin (100, "some message")

VBscript example

world.BroadcastPlugin 100, "Some message"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=BroadcastPlugin)


CallPlugin

Script function

world.CallPlugin

 Read about scripting

Type

Method

Summary

Calls a routine in a plugin

Prototype

long CallPlugin(BSTR PluginID, BSTR Routine, BSTR Argument);

 View list of data type meanings

Description

Calls a nominated routine in a nominated plugin, supplying a string argument.

The intention here is to allow plugins to interact with each other, to a certain extent.

For instance, you might write a plugin that logs text to a log file (or miniwindow), and want to share it between other plugins. Hence you might log a message like this:

  world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"

The above example would locate plugin with the ID 80cc18937a2aca27079567f0 (if installed) and then call the routine "LogIt" in that plugin, with the argument "Data to be logged". In this example, the LogIt routine would look like this:

function LogIt (sText)

  WriteLog (sText)

end -- function LogIt

You should exercise caution when using this technique. It will be annoying for plugin users if plugins become overly dependent on each other, particularly if they cannot find the one that is required.

Also, be careful you do not set up circular dependencies (eg. A needs B, and B needs A).

You can use "PluginSupports" to see if a particular routine is implemented in a plugin. For example:

if PluginSupports ("80cc18937a2aca27079567f0", "LogIt") ~= error_code.eOK then

  Note "Required 'LogIt' routine is not available"

end -- if

If you want to send a message to all installed plugins you might consider using BroadcastPlugin instead.

New in version 4.55: Lua scripts can call Lua plugins using CallPlugin, but pass multiple arguments (not just a single string). Also they can receive returned data. See below for more details.

Return value

eNoSuchPlugin: Plugin not installed

ePluginDisabled: Plugin is disabled

eNoSuchRoutine: Specified routine cannot be found in that plugin

eErrorCallingPluginRoutine: Error when calling function (runtime error) OR - the function returned an unsupported data type (Lua only)

eBadParameter: An argument was an invalid type (Lua only)

eOK: Called OK

 View list of return code meanings

Lua example

CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")

Lua notes

Functions can be nested inside tables. So for example you could call function "foo.bar".

New in version 4.55 onwards:

You can pass multiple arguments which must be one of: nil, boolean, number or string.

The called function can return zero or more values which must also be one of the above types.

For example:

rc, a, b, c, d = CallPlugin ("80cc18937a2aca27079567f0", "show_message", "red", "green", "message", 42)

On an error the second value returned ('a' in the example) will be a string indicating the reason for the error.

On an execution error (eErrorCallingPluginRoutine) there will also be a third return value ('b' in the example) which is the error message generated at runtime.

See:

http://www.gammon.com.au/forum/?id=10453

Jscript example

world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");

PerlScript example

$world->CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged");

Python example

world.CallPlugin ("80cc18937a2aca27079567f0", "LogIt", "Data to be logged")

VBscript example

world.CallPlugin "80cc18937a2aca27079567f0", "LogIt", "Data to be logged"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=CallPlugin)


ChangeDir

Script function

world.ChangeDir

 Read about scripting

Type

Method

Summary

Changes the MUSHclient working directory

Prototype

long ChangeDir(BSTR Path);

 View list of data type meanings

Description

This lets you change the current working directory used by MUSHclient. This is useful for situations (like plugins) where you want to load files relative to the plugin location but are unsure if the working directory is at the plugin location. eg.

  ChangeDir (GetInfo (66))  --> ensure directory is MUSHclient.exe directory

Note that some actions (like opening world files) may change the directory (eg. to the world file directory) as a side-effect.

Return value

0 - Did not change directory

1 - Did it OK

Lua example

ChangeDir (GetInfo (66))

VBscript example

ChangeDir GetInfo (66)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 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 &#x5C;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)

 GetInfo (Gets information about the current world)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=ChangeDir)


ChatAcceptCalls

Script function

world.ChatAcceptCalls

 Read about scripting

Type

Method

Summary

Accepts incoming chat calls

Prototype

long ChatAcceptCalls(short Port);

 View list of data type meanings

Description

Starts accepting incoming chat calls.

The port number specifies which port to listen for the calls on. If zero, the default chat port is used. If non-zero, this will change the default chat port.

This will fail if MUSHclient is already accepting calls.

It will also fail if another program or another world (eg. another MUSHclient window) is already listening for calls on the specified port. Thus, if you are accepting calls in different worlds simultaneously, each one must use a different port.

The default port for chats is 4050.

Return value

eChatAlreadyListening: We are already accepting calls.

eCannotCreateChatSocket: We cannot do that, probably the port is in use.

eOK: Now accepting calls.

 View list of return code meanings

Lua example

ChatAcceptCalls (0)  -- use the default port

ChatAcceptCalls (4051)  -- use port 4051

Lua notes

The Port argument is optional. If omitted it defaults to 4050.

Jscript example

ChatAcceptCalls (0);  // use the default port

ChatAcceptCalls (4051);  // use port 4051

PerlScript example

ChatAcceptCalls (0);  # use the default port

ChatAcceptCalls (4051);  # use port 4051

Python example

world.ChatAcceptCalls (0)  # use the default port

world.ChatAcceptCalls (4051)  # use port 4051

VBscript example

ChatAcceptCalls 0  ' use the default port

ChatAcceptCalls 4051  ' use port 4051

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatAcceptCalls)


ChatCall

Script function

world.ChatCall

 Read about scripting

Type

Method

Summary

Calls a chat server (makes an outgoing call) using the MudMaster chat protocol

Prototype

long ChatCall(BSTR Server, long Port);

 View list of data type meanings

Description

Attempts to establish a chat call to another client. If you know the other client is using zChat you may wish to use ChatCallzChat instead which uses the zChat protocol.

You specify the TCP/IP address and the port number. If the port number is zero the default chat port of 4050 is used.

Because of the asynchronous nature of TCP/IP a "good" status from this call does not necessarily mean you will establish a chat session, it just means it has succeeded in starting the process.

In order to establish a chat session, MUSHclient must:

1. Look up the name using the Domain Name Server (DNS) unless a dotted-decimal name was given - this may take a few seconds.

2. Connect to the chat server - this may take a few more seconds

3. Attempt to negotiate a chat session by sending "CHAT:" to the chat server

4. Await a response - this may take a while if the player at the other end is deciding whether to accept the connection or not.

5. Finally, if all goes well, the chat session is established.

To know if the session was really established you need to use the plugin callback routine "OnPluginChatNewUser" - this notifies you when a new user is established.

Return value

eCannotCreateChatSocket: Cannot start call - perhaps all sockets are in use?

eCannotLookupDomainName: Cannot start looking up domain name

eOK: Call process started OK

 View list of return code meanings

Lua example

ChatCall ("123.45.67.89")     -- call on default port

ChatCall ("123.45.67.89", 4060)  -- call on port 4060

ChatCall ("myfriend.hisdomain.com")    -- call on default port using name

Lua notes

The Port argument is optional. If omitted it defaults to 4050.

Jscript example

ChatCall ("123.45.67.89", 0);     // call on default port

ChatCall ("123.45.67.89", 4060);  // call on port 4060

ChatCall ("myfriend.hisdomain.com", 0);    // call on default port using name

PerlScript example

ChatCall ("123.45.67.89", 0);     # call on default port

ChatCall ("123.45.67.89", 4060);  # call on port 4060

ChatCall ("myfriend.hisdomain.com", 0);    # call on default port using name

Python example

world.ChatCall ("123.45.67.89", 0)     # call on default port

world.ChatCall ("123.45.67.89", 4060)  # call on port 4060

world.ChatCall ("myfriend.hisdomain.com", 0)    # call on default port using name

VBscript example

ChatCall "123.45.67.89", 0     ' call on default port

ChatCall "123.45.67.89", 4060  ' call on port 4060

ChatCall "myfriend.hisdomain.com", 0    ' call on default port using name

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatCall)


ChatCallzChat

Script function

world.ChatCallzChat

 Read about scripting

Type

Method

Summary

Calls a zChat chat server (makes an outgoing call)

Prototype

long ChatCallzChat(BSTR Server, long Port);

 View list of data type meanings

Description

Attempts to establish a chat call to another client using the zChat protocol.

Use ChatCall to call using the MudMaster chat protocol.

You specify the TCP/IP address and the port number. If the port number is zero the default chat port of 4050 is used.

Because of the asynchronous nature of TCP/IP a "good" status from this call does not necessarily mean you will establish a chat session, it just means it has succeeded in starting the process.

In order to establish a chat session, MUSHclient must:

1. Look up the name using the Domain Name Server (DNS) unless a dotted-decimal name was given - this may take a few seconds.

2. Connect to the chat server - this may take a few more seconds

3. Attempt to negotiate a chat session by sending "ZCHAT:" to the chat server

4. Await a response - this may take a while if the player at the other end is deciding whether to accept the connection or not.

5. Finally, if all goes well, the chat session is established.

To know if the session was really established you need to use the plugin callback routine "OnPluginChatNewUser" - this notifies you when a new user is established.

Return value

eCannotCreateChatSocket: Cannot start call - perhaps all sockets are in use?

eCannotLookupDomainName: Cannot start looking up domain name

eOK: Call process started OK

 View list of return code meanings

Lua example

ChatCallzChat ("123.45.67.89")     -- call on default port

ChatCallzChat ("123.45.67.89", 4060)  -- call on port 4060

ChatCallzChat ("myfriend.hisdomain.com")    -- call on default port using name

Lua notes

The Port argument is optional. If omitted it defaults to 4050.

Jscript example

ChatCallzChat ("123.45.67.89", 0);     // call on default port

ChatCallzChat ("123.45.67.89", 4060);  // call on port 4060

ChatCallzChat ("myfriend.hisdomain.com", 0);    // call on default port using name

PerlScript example

ChatCallzChat ("123.45.67.89", 0);     # call on default port

ChatCallzChat ("123.45.67.89", 4060);  # call on port 4060

ChatCallzChat ("myfriend.hisdomain.com", 0);    # call on default port using name

Python example

world.ChatCallzChat ("123.45.67.89", 0)     # call on default port

world.ChatCallzChat ("123.45.67.89", 4060)  # call on port 4060

world.ChatCallzChat ("myfriend.hisdomain.com", 0)    # call on default port using name

VBscript example

ChatCallzChat "123.45.67.89", 0     ' call on default port

ChatCallzChat "123.45.67.89", 4060  ' call on port 4060

ChatCallzChat "myfriend.hisdomain.com", 0    ' call on default port using name

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatCallzChat)


ChatDisconnect

Script function

world.ChatDisconnect

 Read about scripting

Type

Method

Summary

Disconnects a current chat call

Prototype

long ChatDisconnect(long ID);

 View list of data type meanings

Description

Disconnects an existing chat call.

The call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If a file transfer is in progress it is aborted.

The plugin callback routine "OnPluginChatUserDisconnect" will be called for this user.

Return value

eChatIDNotFound: That chat ID was not found

eOK: Disconnected OK

 View list of return code meanings

Lua example

ChatDisconnect (5)  -- disconnect chat user 5

ChatDisconnect (ChatGetID ("nick"))  -- disconnect nick

Jscript example

ChatDisconnect (5);  // disconnect chat user 5

ChatDisconnect (ChatGetID ("nick"));  // disconnect nick

PerlScript example

ChatDisconnect (5);  #/ disconnect chat user 5

ChatDisconnect (ChatGetID ("nick"));  # disconnect nick

Python example

world.ChatDisconnect (5)  # disconnect chat user 5

world.ChatDisconnect (world.ChatGetID ("nick"))  # disconnect nick

VBscript example

ChatDisconnect 5  ' disconnect chat user 5

ChatDisconnect ChatGetID ("nick")  ' disconnect nick

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatDisconnect)


ChatDisconnectAll

Script function

world.ChatDisconnectAll

 Read about scripting

Type

Method

Summary

Disconnects all current chat calls

Prototype

long ChatDisconnectAll();

 View list of data type meanings

Description

Disconnects all existing chat calls.

If any file transfers are in progress they wil be aborted.

The plugin callback routine "OnPluginChatUserDisconnect" will be called for each user.

If you want to know which calls are currently connected, use GetChatList.

Return value

A count of the number of calls disconnected.

Lua example

ChatDisconnectAll ()

Jscript example

ChatDisconnectAll ();

PerlScript example

ChatDisconnectAll ();

Python example

world.ChatDisconnectAll

VBscript example

ChatDisconnectAll

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatDisconnectAll)


ChatEverybody

Script function

world.ChatEverybody

 Read about scripting

Type

Method

Summary

Sends a chat message to every connected chat user

Prototype

long ChatEverybody(BSTR Message, BOOL Emote);

 View list of data type meanings

Description

This sends a "say" or "emote" to all connected chat users, excepting the ones you are ignoring, if any.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on other people's clients:

Nick chats to everybody, 'hi there'

If you "emote" the message, it will appear like this on other people's clients:

Nick laughs

Return value

eNoChatConnections: No connections (that are not being ignored)

eOK: Sent to at least one person

 View list of return code meanings

Lua example

ChatEverybody ("hi there", 0)  -- say it

ChatEverybody ("laughs", 1)  -- emote it

Lua notes

The Emote argument is optional and defaults to false.

Jscript example

ChatEverybody ("hi there", 0);  // say it

ChatEverybody ("laughs", 1);  // emote it

PerlScript example

ChatEverybody ("hi there", 0);  # say it

ChatEverybody ("laughs", 1);  # emote it

Python example

world.ChatEverybody ("hi there", 0)  # say it

world.ChatEverybody ("laughs", 1)  # emote it

VBscript example

ChatEverybody "hi there", 0  ' say it

ChatEverybody "laughs", 1  ' emote it

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatEverybody)


ChatGetID

Script function

world.ChatGetID

 Read about scripting

Type

Method

Summary

Looks up what chat ID (identifier) corresponds to a particular chat name

Prototype

long ChatGetID(BSTR Who);

 View list of data type meanings

Description

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If more than one person has that name the first one (earliest connection) is returned.

If no person has that name zero is returned.

A message is sent to the output window, so you can use ChatGetID in scripts and have them automatically notify you if that person cannot be found.

Return value

The chat ID corresponding to that name, or zero if none is found.

Lua example

ChatID (ChatGetID ("nick"), "hi there", 0)

Jscript example

ChatID (ChatGetID ("nick"), "hi there", 0);

PerlScript example

ChatID (ChatGetID ("nick"), "hi there", 0);

Python example

world.ChatID (world.ChatGetID ("nick"), "hi there", 0)

VBscript example

ChatID ChatGetID ("nick"), "hi there", 0

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatGetID)


ChatGroup

Script function

world.ChatGroup

 Read about scripting

Type

Method

Summary

Sends a chat message to every connected chat user in the specified group

Prototype

long ChatGroup(BSTR Group, BSTR Message, BOOL Emote);

 View list of data type meanings

Description

This sends a "say" or "emote" to all connected chat users in the specified group, excepting the ones you are ignoring, if any.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on other people's clients:

Nick chats to the group, 'hi'

If you "emote" the message, it will appear like this on other people's clients:

To the group, Nick laughs

To put a particular chat user into a group, use SetChatOption, like this:

world.SetChatOption 5, "group", "friends" ' put user 5 into group friends

Return value

eBadParameter: No group name specified

eNoChatConnections: No connections in that group (that are not being ignored)

eOK: Sent to at least one person

 View list of return code meanings

Lua example

ChatGroup ("friends", "hi there")  -- say it

ChatGroup ("friends", "laughs", true)  -- emote it

Lua notes

The Emote argument is optional and defaults to false.

Jscript example

ChatGroup ("friends", "hi there", 0);  // say it

ChatGroup ("friends", "laughs", 1);  // emote it

PerlScript example

ChatGroup ("friends", "hi there", 0);  # say it

ChatGroup ("friends", "laughs", 1);  # emote it

Python example

world.ChatGroup ("friends", "hi there", 0)  # say it

world.ChatGroup ("friends", "laughs", 1)  # emote it

VBscript example

ChatGroup "friends", "hi there", 0  ' say it

ChatGroup "friends", "laughs", 1  ' emote it

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatGroup)


ChatID

Script function

world.ChatID

 Read about scripting

Type

Method

Summary

Sends a chat message to a particular chat session

Prototype

long ChatID(long ID, BSTR Message, BOOL Emote);

 View list of data type meanings

Description

This sends a "say" or "emote" to the with that Chat ID.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on that person's client:

Nick chats to you, 'hi there'

If you "emote" the message, it will appear like this on that person's client:

To you, Nick laughs

The different message (compared to ChatEverybody or ChatGroup) is so you can tell the message was addressed to you personally.

The message will be sent even if you have set the "ignore" flag on that person, as presumably you want to override it, if you are addressing a message to them directly.

Return value

eChatIDNotFound: No person of that ID is connected

eOK: Sent to at least one person

 View list of return code meanings

Lua example

ChatID (5, "hi there")  -- say it

ChatID (5, "laughs", true)  -- emote it

Lua notes

The Emote argument is optional and defaults to false.

Jscript example

ChatID (5, "hi there", 0);  // say it

ChatID (5, "laughs", 1);  // emote it

PerlScript example

ChatID (5, "hi there", 0);  # say it

ChatID (5, "laughs", 1);  # emote it

Python example

world.ChatID (5, "hi there", 0)  # say it

world.ChatID (5, "laughs", 1)  # emote it

VBscript example

ChatID 5, "hi there", 0  ' say it

ChatID 5, "laughs", 1  ' emote it

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatID)


ChatMessage

Script function

world.ChatMessage

 Read about scripting

Type

Method

Summary

Sends a message to a chat user (raw format)

Prototype

long ChatMessage(long ID, short Message, BSTR Text);

 View list of data type meanings

Description

This sends a "raw" chat message to the particular chat user identified by the chat ID.

You would not normally use this, as this is a low-level routine which is used by other script functions (such as ChatPersonal).

However you could use it to do custom chat messages (eg. use message number 200) which the receiving client could pick up in a plugin callback routine.

For an example of doing that, see:

http://www.gammon.com.au/mushclient/chat.htm#EXAMPLE

Another possible use would be to send chat messages with custom colours, or custom formatting (eg. different colours).

The "Message" argument is the chat message number, which is used at the start of the chat message. These numbers are currently defined:

   1    Name_change

   2    Request_connections

   3    Connection_list

   4    Text_everybody

   5    Text_personal

   6    Text_group

   7    Message

   8    Do_not_disturb

   9    Send_action

  10    Send_alias

  11    Send_macro

  12    Send_variable

  13    Send_event

  14    Send_gag

  15    Send_highlight

  16    Send_list

  17    Send_array

  18    Send_baritem

  19    Version

  20    File_start

  21    File_deny

  22    File_block_request

  23    File_block

  24    File_end

  25    File_cancel

  26    Ping_request

  27    Ping_response

  28    Peek_connections

  29    Peek_list

  30    Snoop

  31    Snoop_data

 105    Send_command

The "Text" argument is the text of the message to be sent. It can be empty. See the chat specifications for more details about what should be in the text field. You do *not* need to put the message number at the start of the text field, nor do you need to put the message terminator (hex FF) at the end of the text field. MUSHclient does that for you automatically.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

Return value

eChatIDNotFound: That chat ID is not connected

eOK: Sent OK

 View list of return code meanings

Lua example

ChatMessage (ChatGetID ("fred"), 30)  -- start snooping Fred

--

--  do a custom coloured "chat to everybody" (using bold magenta)

--

-- (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4,

             "n" .. ANSI (35) .. ANSI (1) ..

             "<CHAT> The chat system is great!n")

Lua notes

The message is optional and defaults to the empty string.

Jscript example

ChatMessage (ChatGetID ("fred"), 30, "");  // start snooping Fred

//

//  do a custom coloured "chat to everybody" (using bold magenta)

//

// (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4,

             "\n" + ANSI (35) + ANSI (1) +

             "<CHAT> The chat system is great!\n");

PerlScript example

ChatMessage (ChatGetID ("fred"), 30, "");  # start snooping Fred

#

#  do a custom coloured "chat to everybody" (using bold magenta)

#

# (The chat is only sent to connection Bruce, however)

ChatMessage (ChatGetID ("bruce"), 4,

             "\n" . ANSI (35) . ANSI (1) .

             "<CHAT> The chat system is great!\n");

Python example

world.ChatMessage (world.ChatGetID ("fred"), 30, "")  # start snooping Fred

#

#  do a custom coloured "chat to everybody" (using bold magenta)

#

# (The chat is only sent to connection Bruce, however)

world.ChatMessage (world.ChatGetID ("bruce"), 4,

             "n" + world.ANSI (35) + world.ANSI (1) +

             "<CHAT> The chat system is great!n")

VBscript example

ChatMessage ChatGetID ("fred"), 30, ""  ' start snooping Fred

'

'  do a custom coloured "chat to everybody" (using bold magenta)

'

' (The chat is only sent to connection Bruce, however)

'

ChatMessage ChatGetID ("bruce"), 4, _

             vbCrLf & ANSI (35) & ANSI (1) & _

             "<CHAT> The chat system is great!" & _

             vbCrLf

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatMessage)


ChatNameChange

Script function

world.ChatNameChange

 Read about scripting

Type

Method

Summary

Changes your chat name

Prototype

long ChatNameChange(BSTR NewName);

 View list of data type meanings

Description

This changes your chat name - the name other people see when connecting to you, or when you connect to them. A message is sent to all directly connected users notifying them of the name change, so their clients should show the new name immediately.

Return value

eBadParameter: No name supplied

eOK: Name changed

 View list of return code meanings

Lua example

ChatNameChange ("Krenath")

Jscript example

ChatNameChange ("Krenath");

PerlScript example

ChatNameChange ("Krenath");

Python example

world.ChatNameChange ("Krenath")

VBscript example

ChatNameChange "Krenath"

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatNameChange)


ChatNote

Script function

world.ChatNote

 Read about scripting

Type

Method

Summary

Does a note using ANSI codes for the chat system

Prototype

void ChatNote(short NoteType, BSTR Message);

 View list of data type meanings

Description

This is used internally by the chat system to put notes on the screen in the current chat colour.

First, it calls the plugin callback routine "OnPluginChatDisplay" for each installed plugin, and passes the NoteType and Message to it. This gives the plugin a chance to do its own thing with the message (for instance, display it in a notepad window).

If any plugin returns False (0) then ChatNote exits without doing anything else (including calling other plugins later down the list).

However if all plugins return true (or don't have a "OnPluginChatDisplay" handler) then ChatNote then does the following:

1. Save the current note colour.

2. Change the note colour to the "chat_foreground_colour" and "chat_background_colour" from the world preferences. If they are both the same, it takes the default chat colour of red on black.

3. Removes a leading newline, if any.

4. Removes a trailing newline, if any.

5. If the world preferences option "ignore_chat_colours" is set, the ANSI codes are stripped from the message.

6. The message is displayed (using AnsiNote).

7. The saved note colour is restored.

The NoteType argument is used to identify "types" of chats to the plugin callback routine. These types are currently defined:

   0 Connection attempt

   1 Session start, end

   2 Name Change

   3 Message

   4 Incoming Personal

   5 Incoming Everybody

   6 Incoming roup

   7 Outgoing Personal

   8 Outgoing Everybody

   9 Outgoing Group

  10 Peek List

  11 Connection List

  12 Ping

  13 Information

  14 File

  15 Snoop Data

  16 Command

You could use those to send some types of messages (eg. connection attempts) to the main world window, but other types to a notepad window.

Return value

Nothing.

Lua example

ChatNote (3, "<CHAT> My plugin is now installed")

Lua notes

The message is optional and defaults to the empty string.

Jscript example

ChatNote (3, "<CHAT> My plugin is now installed");

PerlScript example

ChatNote (3, "<CHAT> My plugin is now installed");

Python example

world.ChatNote (3, "<CHAT> My plugin is now installed")

VBscript example

ChatNote 3, "<CHAT> My plugin is now installed"

See Also ...

Topics

 Chat system

 Getting started

Functions

 ANSI (Generates an ANSI colour sequence)

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 ColourNote (Sends a message to the output window in specified colours)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 GetOption (Gets value of a named world option)

 Note (Sends a note to the output window)

 SetChatOption (Sets the value of a chat session option)

 SetOption (Sets value of a named world option)

(Help topic: function=ChatNote)


ChatPasteEverybody

Script function

world.ChatPasteEverybody

 Read about scripting

Type

Method

Summary

Pastes the clipboard contents to every connected person

Prototype

long ChatPasteEverybody();

 View list of data type meanings

Description

This pastes the clipboard contents to everybody (who you are not ignoring).

The clipboard must contain text - if it does the entire contents will be pasted to that everybody (as an "everybody" chat message, so it will work with other clients), and echoed on your output window as well.

You could use that to exchange aliases, triggers, messages from the screen, and so on.

Return value

eNoChatConnections: No chat connetions found

eClipboardEmpty: No text on the clipboard

eOK: Sent OK

 View list of return code meanings

Lua example

ChatPasteEverybody ()

Jscript example

ChatPasteEverybody ();

PerlScript example

ChatPasteEverybody ();

Python example

world.ChatPasteEverybody

VBscript example

ChatPasteEverybody

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatPasteEverybody)


ChatPasteText

Script function

world.ChatPasteText

 Read about scripting

Type

Method

Summary

Pastes the clipboard contents to that person

Prototype

long ChatPasteText(long ID);

 View list of data type meanings

Description

This pastes the clipboard contents to the person with that chat ID.

The clipboard must contain text - if it does the entire contents will be pasted to that person (as a personal chat message, so it will work with other clients), and echoed on your output window as well.

You could use that to exchange aliases, triggers, messages from the screen, and so on.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

Return value

eChatIDNotFound: No call with that chat ID

eClipboardEmpty: No text on the clipboard

eOK: Sent OK

 View list of return code meanings

Lua example

ChatPasteText (5)   -- paste to user 5

ChatPasteText (ChatGetID ("nick"))  -- paste to Nick

Jscript example

ChatPasteText (5);   // paste to user 5

ChatPasteText (ChatGetID ("nick"));  // paste to Nick

PerlScript example

ChatPasteText (5);   # paste to user 5

ChatPasteText (ChatGetID ("nick"));  # paste to Nick

Python example

world.ChatPasteText (5)   # paste to user 5

world.ChatPasteText (world.ChatGetID ("nick"))  # paste to Nick

VBscript example

ChatPasteText 5  ' paste to user 5

ChatPasteText ChatGetID ("nick")  ' paste to Nick

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatPasteText)


ChatPeekConnections

Script function

world.ChatPeekConnections

 Read about scripting

Type

Method

Summary

Sends a "peek connections" message to the specified chat user

Prototype

long ChatPeekConnections(long ID);

 View list of data type meanings

Description

Requests the specified chat user to send a list of its public connections. This is the same as doing this:

ChatMessage ID, 28, ""

The chat user who receives that will (should) respond with a list of their current chat connections that they have (excluding the connection to you), so you can see who else they are chatting with.

If you want to connect to those users automatically, use ChatRequestConnections.

Return value

eChatIDNotFound: That chat ID is not currently connected.

eOK: Peek message sent.

 View list of return code meanings

Lua example

ChatPeekConnections (ChatGetID ("nick"))

Jscript example

ChatPeekConnections (ChatGetID ("nick"));

PerlScript example

ChatPeekConnections (ChatGetID ("nick"));

Python example

world.ChatPeekConnections (world.ChatGetID ("nick"))

VBscript example

ChatPeekConnections ChatGetID ("nick")

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatPeekConnections)


ChatPersonal

Script function

world.ChatPersonal

 Read about scripting

Type

Method

Summary

Sends a chat message to a particular person

Prototype

long ChatPersonal(BSTR Who, BSTR Message, BOOL Emote);

 View list of data type meanings

Description

This sends a "say" or "emote" to the person(s) of that name.

If more than one person has the specified name, all will get the message. If this is a problem, use ChatID to send a message to a specific user by number rather than name.

If the "emote" parameter is zero (false) then you will "say" the message, otherwise you will emote it.

If you "say" the message, it will appear like this on that person's client:

Nick chats to you, 'hi there'

If you "emote" the message, it will appear like this on that person's client:

To you, Nick laughs

The different message (compared to ChatEverybody or ChatGroup) is so you can tell the message was addressed to you personally.

The message will be sent even if you have set the "ignore" flag on that person, as presumably you want to override it, if you are addressing a message to them directly.

Return value

eChatPersonNotFound: No person of that name connected

eOK: Sent to at least one person

 View list of return code meanings

Lua example

ChatPersonal ("nick", "hi there")  -- say it

ChatPersonal ("nick", "laughs", true)  -- emote it

Lua notes

The Emote argument is optional and defaults to false.

Jscript example

ChatPersonal ("nick", "hi there", 0);  // say it

ChatPersonal ("nick", "laughs", 1);  // emote it

PerlScript example

ChatPersonal ("nick", "hi there", 0);  # say it

ChatPersonal ("nick", "laughs", 1);  # emote it

Python example

world.ChatPersonal ("nick", "hi there", 0)  # say it

world.ChatPersonal ("nick", "laughs", 1)  # emote it

VBscript example

ChatPersonal "Nick", "hi there", 0  ' say it

ChatPersonal "Nick", "laughs", 1  ' emote it

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatPersonal)


ChatPing

Script function

world.ChatPing

 Read about scripting

Type

Method

Summary

Sends a ping message to the specified chat user

Prototype

long ChatPing(long ID);

 View list of data type meanings

Description

This sends a "ping request" chat message (26) (not an ICMP message) to the specified chat user. They should response by echoing the message back with a "ping response" message type (27).

MUSHclient makes a note of the time the ping message was sent, so that when the ping response arrives, it can work out how long the ping took for the round trip.

Return value

eChatIDNotFound: The chat ID was not connected.

eOK: Ping message sent.

 View list of return code meanings

Lua example

ChatPing (ChatGetID ("john"))

Jscript example

ChatPing (ChatGetID ("john"));

PerlScript example

ChatPing (ChatGetID ("john"));

Python example

world.ChatPing (world.ChatGetID ("john"))

VBscript example

ChatPing ChatGetID ("john")

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatPing)


ChatRequestConnections

Script function

world.ChatRequestConnections

 Read about scripting

Type

Method

Summary

Sends a "request connections" message to the specified chat user

Prototype

long ChatRequestConnections(long ID);

 View list of data type meanings

Description

Requests the specified chat user to send a list of its public connections. This is the same as doing this:

ChatMessage ID, 2, ""

The chat user who receives that will (should) respond with a list of their current chat connections that they have (excluding the connection to you. MUSHclient will then try to connect to them directly (so that you can chat with them without having to go through the other person, for example, in case they disconnect).

If you want to see who those users are first, use ChatPeekConnections.

Return value

eChatIDNotFound: That chat ID is not currently connected.

eOK: Request connections message sent.

 View list of return code meanings

Lua example

ChatRequestConnections(ChatGetID ("nick"))

Jscript example

ChatRequestConnections(ChatGetID ("nick"));

PerlScript example

ChatRequestConnections(ChatGetID ("nick"));

Python example

world.ChatRequestConnections(world.ChatGetID ("nick"))

VBscript example

ChatRequestConnectionsChatGetID ("nick")

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatRequestConnections)


ChatSendFile

Script function

world.ChatSendFile

 Read about scripting

Type

Method

Summary

Starts sending a file to the specified chat user

Prototype

long ChatSendFile(long ID, BSTR FileName);

 View list of data type meanings

Description

This starts the process of sending a file to the specified chat ID.

If the file name is empty, then you will be prompted with a "choose file" dialog box, so you can pick the file with the normal Window file browser.

If the file name is not empty, then MUSHclient will attempt to send that file.

The recipient of the file must have allowed file sending, or you will get an error message.

You cannot send more than one file at a time - you will get an error if you attempt to send a file whilst sending, or receiving, another one (to that user).

You can use GetChatInfo to see if a file transfer is in progres.

You can use SetChatOption to set the "can_send_files" flag.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

Note that an "OK" response merely means that we have sent a request to the other user to accept the file. There is no guarantee that s/he will want it.

Return value

eChatIDNotFound: That chat ID is not connected

eAlreadyTransferringFile: Already transferring a file

eFileNotFound: That file not found, or user cancelled file picker dialog box

eOK: File transfer initiated

 View list of return code meanings

Lua example

ChatSendFile (ChatGetID ("fred")) -- send a file that you choose

Lua notes

The file name is optional. If omitted you will be prompted for one.

Jscript example

ChatSendFile (ChatGetID ("fred"), ""); // send a file that you choose

PerlScript example

ChatSendFile (ChatGetID ("fred"), "");  # send a file that you choose

Python example

world.ChatSendFile (world.ChatGetID ("fred"), "") # send a file that you choose

VBscript example

ChatSendFile ChatGetID ("fred"), ""  ' send a file that you choose

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatSendFile)


ChatStopAcceptingCalls

Script function

world.ChatStopAcceptingCalls

 Read about scripting

Type

Method

Summary

Stops this world from accepting chat calls

Prototype

void ChatStopAcceptingCalls();

 View list of data type meanings

Description

Stops the world from accepting incoming chat calls. Existing calls are not affected. What this does is close the "listening" socket, so that the client no longer "hears" incoming calls.

Use ChatDisconnect or ChatDisconnectAll to disconnect existing calls.

Return value

Nothing.

Lua example

ChatStopAcceptingCalls ()

Jscript example

ChatStopAcceptingCalls ();

PerlScript example

ChatStopAcceptingCalls ();

Python example

world.ChatStopAcceptingCalls

VBscript example

ChatStopAcceptingCalls

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatStopAcceptingCalls)


ChatStopFileTransfer

Script function

world.ChatStopFileTransfer

 Read about scripting

Type

Method

Summary

Stops a file transfer in progress to that chat user

Prototype

long ChatStopFileTransfer(long ID);

 View list of data type meanings

Description

If a file transfer is in progress (send or receive) it is aborted, and the user at the other end notified, if possible.

You can use GetChatInfo to see if a file transfer is in progress.

Each call is identified by its "chat ID" - each chat session has a unique ID, which starts at one, and is incremented by one, per world.

You can use GetChatList to find a list of chat IDs that is current.

You can use ChatGetID to find the chat ID corresponding to a particular chat name.

Return value

eChatIDNotFound: That chat ID is not connected.

eNotTransferringFile: We are not transferring a file.

eOK: File transfer aborted.

 View list of return code meanings

Lua example

ChatStopFileTransfer (ChatGetID ("peter"))

Jscript example

ChatStopFileTransfer (ChatGetID ("peter"));

PerlScript example

ChatStopFileTransfer (ChatGetID ("peter"));

Python example

world.ChatStopFileTransfer (world.ChatGetID ("peter"))

VBscript example

ChatStopFileTransfer ChatGetID ("peter")

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=ChatStopFileTransfer)


CloseLog

Script function

world.CloseLog

 Read about scripting

Type

Method

Summary

Closes the log file

Prototype

long CloseLog();

 View list of data type meanings

Description

This closes the currently open log file.

If you have a log file postamble declared this is written to the log file (note that this is inconsistent with what OpenLog does).

Return value

eOK: closed OK

eLogFileNotOpen: log file was not open

 View list of return code meanings

Lua example

CloseLog()

Jscript example

world.closelog();

PerlScript example

$world->closelog;

Python example

world.closelog

VBscript example

world.closelog

See Also ...

Topic

 Logging

Functions

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=CloseLog)


CloseNotepad

Script function

world.CloseNotepad

 Read about scripting

Type

Method

Summary

Closes a notepad window

Prototype

long CloseNotepad(BSTR Title, BOOL QuerySave);

 View list of data type meanings

Description

This closes a notepad window.

Title - title of the notepad (used in functions like AppendToNotepad)

QuerySave - whether to query to save changes, if the contents of the window have changed.

Return value

1 = closed OK

0 = not closed

Lua example

CloseNotepad ("my_notepad", 0)

Lua notes

The QuerySave argument is optional, and defaults to false.

Jscript example

world.CloseNotepad ("my_notepad", 0);

PerlScript example

$world->CloseNotepad ("my_notepad", 0);

Python example

world.CloseNotepad ("my_notepad", 0)

VBscript example

world.CloseNotepad "my_notepad", 0

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=CloseNotepad)


ColourNameToRGB

Script function

world.ColourNameToRGB

 Read about scripting

Type

Method

Summary

Converts a named colour to a RGB colour code.

Prototype

long ColourNameToRGB(BSTR Name);

 View list of data type meanings

Description

Converts a named colour (eg. "brown") to an RGB colour code (eg. 2763429).

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"

Return value

The RGB code of the converted colour, or -1 if the colour name is not recognised. Note that -1 cannot be an RGB colour (-1 is the hex sequence 0xFFFFFFFF, whereas the "highest" colour (white) is hex 0x00FFFFFF).

Lua example

Note (ColourNameToRGB ("brown"))

Jscript example

world.note (world.colourNameToRGB ("brown"));

PerlScript example

$world->note ($world->colourNameToRGB ("brown"));

Python example

world.note (world.colourNameToRGB ("brown"))

VBscript example

world.note world.colourNameToRGB ("brown")

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 Debug (Displays debugging information about the world)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=ColourNameToRGB)


ColourNote

Script function

world.ColourNote

 Read about scripting

Type

Method

Summary

Sends a message to the output window in specified colours

Prototype

void ColourNote(BSTR TextColour, BSTR BackgroundColour, BSTR Text);

 View list of data type meanings

Description

This lets you do a "note" in a specified colour. It is not transmitted to the world. It is useful for making comments to yourself. The note colour is saved and restored, so that the world note colour is unchanged after using this function (however the new colour is used for the tell itself).

eg.

  world.ColourNote "red", "blue", "Hello there"

The colour is specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug "colours". You can also specify colours in HTML format, like this:

  world.ColourNote "#FAEBD7", "#FFB6C1", "Hi there"

If you leave a colour name blank, it is unchanged. Thus you could do this to get red text on the existing background:

  world.ColourNote "red", "", "Hello there"

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or n in Jscript or Perlscript.

To make changes to the text style (eg. bold, underline) see NoteStyle.

Return value

Nothing.

Lua example

ColourNote ("red", "blue", "Hello there ",

            "white", "green", "everyone")

Lua notes

You can supply any number of arguments, however they must be in groups of three:

* foreground colour

* background colour

* text

The example above shows how you might send two lots of text coloured different ways.

The newline is only appended to the end of the note, not between individual items.

Jscript example

world.ColourNote ("red", "blue", "Hello there");

PerlScript example

$world->ColourNote ("red", "blue", "Hello there");

Python example

world.ColourNote ("red", "blue", "Hello there")

VBscript example

world.ColourNote "red", "blue", "Hello there"

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ChatNote (Does a note using ANSI codes for the chat system)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteStyle (Sets the style for notes)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 Send (Sends a message to the MUD)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=ColourNote)


ColourTell

Script function

world.ColourTell

 Read about scripting

Type

Method

Summary

Sends a message to the output window in specified colours - not terminated by a newline

Prototype

void ColourTell(BSTR TextColour, BSTR BackgroundColour, BSTR Text);

 View list of data type meanings

Description

This lets you do a "tell" in a specified colour. It is not transmitted to the world. It is useful for making comments to yourself. The note is NOT automatically terminated by a newline, so you can use ColourTell multiple times on one line (eg. to change colour in mid-line). The note colour is saved and restored, so that the world note colour is unchanged after using this function (however the new colour is used for the tell itself).

eg.

  world.ColourTell "red", "blue", "Hello there"

The colour is specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug "colours". You can also specify colours in HTML format, like this:

  world.ColourTell "#FAEBD7", "#FFB6C1", "Hi there"

If you leave a colour name blank, it is unchanged. Thus you could do this to get red text on the existing background:

  world.ColourTell "red", "", "Hello there"

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or n in Jscript or Perlscript.

To make changes to the text style (eg. bold, underline) see NoteStyle.

Return value

Nothing.

Lua example

ColourTell ("red", "blue", "Hello there ",

            "white", "green", "everyone")

Lua notes

You can supply any number of arguments, however they must be in groups of three:

* foreground colour

* background colour

* text

The example above shows how you might send two lots of text coloured different ways.

Jscript example

world.ColourTell ("red", "blue", "Hello ");

world.ColourTell ("white", "green", "there");

PerlScript example

$world->ColourTell ("red", "blue", "Hello ");

$world->ColourTell ("white", "green", "there");

Python example

world.ColourTell ("red", "blue", "Hello ")

world.ColourTell ("white", "green", "there")

VBscript example

world.ColourTell "red", "blue", "Hello "

world.ColourTell "white", "green", "there"

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteStyle (Sets the style for notes)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 Send (Sends a message to the MUD)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=ColourTell)


Connect

Script function

world.Connect

 Read about scripting

Type

Method

Summary

Connects the world to the MUD server

Prototype

long Connect();

 View list of data type meanings

Description

This connects the current world. Note that since connecting is "asynchronous" you are not actually connected when this command completes. A return value of eOK simply means that the connection process has successfully started.

You can use IsConnected to see if the world is currently connected.

Return value

eWorldOpen: world is already open

eOK: initiated connection

 View list of return code meanings

Lua example

Connect()

Jscript example

world.connect();

PerlScript example

$world->connect;

Python example

world.connect

VBscript example

world.connect

See Also ...

Functions

 Disconnect (Disconnects the world from the MUD server)

 IsConnected (Tests to see if the world is connected to the MUD server)

 ResetIP (Resets the cached IP address of the world and proxy server)

(Help topic: function=Connect)


CreateGUID

Script function

world.CreateGUID

 Read about scripting

Type

Method

Summary

Creates a GUID - Global Unique Identifier

Prototype

BSTR CreateGUID();

 View list of data type meanings

Description

This generates a unique GUID (Global Unique Identifier). This is almost certain to be unique throughout the world, and at any time (ie. completely and utterly unique).

The GUID will look like this: 6B29FC40-CA47-1067-B31D-00DD010662DA

The purpose of this is to give you a way of having a unique identifier (eg. for a variable). If you were to use it for that purpose you would have to add a letter to the front, as variables must start with a letter, not a number, and change hyphens to underscores. eg.

   dim uniqueid

    uniqueid = "X" & world.replace (world.createguid, "-", "_", true)

These numbers may seem cumbersome, but at least if you use them you are guaranteed of a unique identifier.

Contrast this to "GetUniqueNumber" which only returns a unique number for this session of MUSHclient. Thus, the numbers (from "GetUniqueNumber") will not be unique over multiple sessions.

See also the new script function world.GetUniqueID.

Also, using random number generation for unique identifiers has a chance of returning the same number, depending on a) the seed given to the generator; and b) the way the generator must eventually recyle and regenerate the same sequence.

Return value

A 36-character GUID.

Lua example

Note (CreateGUID ())

Jscript example

world.Note (world.CreateGUID ());

PerlScript example

$world->Note ($world->CreateGUID ());

Python example

world.Note (world.CreateGUID )

VBscript example

world.Note world.CreateGUID

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=CreateGUID)


CustomColourBackground

Script function

world.CustomColourBackground

 Read about scripting

Type

Property

Summary

Sets the RGB value for the background of a custom colour

Prototype

long CustomColourBackground(short WhichColour);

void CustomColourBackground(short WhichColour, long nNewValue);

 View list of data type meanings

Description

You can use this property to get or set the RGB colours used for the background of the 16 custom colours. You must specify *which* colour you want to get/set, in the range 1 to 16.

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour, BoldColour and CustomColourText.

Return value

This is a property. You can use it to find the current custom background colour.

Lua example

Note (GetCustomColourBackground (10))

SetCustomColourBackground (14, 0)

Lua notes

Lua implements this as two functions:

GetCustomColourBackground - gets the custom colour background

SetCustomColourBackground - sets the custom colour background

Jscript example

world.Note(world.customcolourbackground(10));

world.customcolourbackground(14) = 0;

PerlScript example

$world->Note($world->customcolourbackground(10));

Python example

world.Note(world.customcolourbackground(10))

world.customcolourbackground(14) = 0

VBscript example

world.note world.customcolourbackground (10)

world.customcolourbackground (14) = vbBlack

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=CustomColourBackground)


CustomColourText

Script function

world.CustomColourText

 Read about scripting

Type

Property

Summary

Sets the RGB value for the text of a custom colour

Prototype

long CustomColourText(short WhichColour);

void CustomColourText(short WhichColour, long nNewValue);

 View list of data type meanings

Description

You can use this property to get or set the RGB colours used for the text (foreground) of the 16 custom colours. You must specify *which* colour you want to get/set, in the range 1 to 16.

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also NormalColour, BoldColour and CustomColourBackground.

Return value

This is a property. You can use it to find the current custom text colour.

Lua example

Note(GetCustomColourText (10))

SetCustomColourText (14, ColourNameToRGB ("brown"))

Lua notes

Lua implements this as two functions:

GetCustomColourText - gets the custom colour text

SetCustomColourText - sets the custom colour text

Jscript example

world.Note(world.customcolourtext(10));

world.customcolourtext(14) = 0xFF0000;

PerlScript example

$world->Note($world->customcolourtext(10));

Python example

world.Note(world.customcolourtext(10))

world.customcolourtext(14) = 0xFF0000

VBscript example

world.note world.customcolourtext (10)

world.customcolourtext (14) = vbBlue

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=CustomColourText)


DatabaseChanges

Script function

world.DatabaseChanges

 Read about scripting

Type

Method

Summary

Returns a count of the changes to the database by the most recent SQL statement

Prototype

long DatabaseChanges(BSTR DbName);

 View list of data type meanings

Description

This function returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement on the database connection specified by the first parameter. Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted. Auxiliary changes caused by triggers are not counted. Use the DatabaseTotalChanges function to find the total number of changes including changes caused by triggers.

Return value

A positive integer, or zero, indicating the count of changes.

Otherwise:

-1 : Database id not found

-2 : Database not open

Lua example

changes = DatabaseChanges ("db")

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseChanges)


DatabaseClose

Script function

world.DatabaseClose

 Read about scripting

Type

Method

Summary

Closes an SQLite database

Prototype

long DatabaseClose(BSTR DbName);

 View list of data type meanings

Description

Closes an existing SQLite database.

DbName - the unique database ID you assigned when opening the database.

Return value

0: Closed OK

-1 : Database id not found

-2 : Database not open

Lua example

DatabaseClose ("db")  -- close it

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseClose)


DatabaseColumnName

Script function

world.DatabaseColumnName

 Read about scripting

Type

Method

Summary

Find the name of a specified column returned by an SQL statement

Prototype

BSTR DatabaseColumnName(BSTR DbName, long Column);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabasePrepare, to find the names of columns that each row will return.

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

The column name is the name given in the "AS" clause in the query, if any. Otherwise SQLite assigns a column name, which is not guaranteed to be consistent between versions. Often the column name will simply be the name of the variable being queried, however calculations may return generated names.

For example, using this SQL statement:

DatabasePrepare ("db", "SELECT name AS 'weapon name', damage * 5 from weapons")

The returned column names were 'weapon name' and 'damage * 5'.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Also see DatabaseColumnNames which returns a table of all the column names.

Return value

The name of the column.

If a parameter is invalid (eg. database not open, bad column number) an empty string is returned.

Lua example

name = DatabaseColumnName ("db", 5)  --> the name of column 5

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnName)


DatabaseColumnNames

Script function

world.DatabaseColumnNames

 Read about scripting

Type

Method

Summary

Return a table of all the columns returned by an SQL statement

Prototype

VARIANT DatabaseColumnNames(BSTR DbName);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabasePrepare, to find the names of columns that each row will return.

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

The column name is the name given in the "AS" clause in the query, if any. Otherwise SQLite assigns a column name, which is not guaranteed to be consistent between versions. Often the column name will simply be the name of the variable being queried, however calculations may return generated names.

For example, using this SQL statement:

DatabasePrepare ("db", "SELECT name AS 'weapon name', damage * 5 from weapons")

The returned column names were 'weapon name' and 'damage * 5'.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Also see DatabaseColumnName which returns an entry for a single column.

Return value

A table of all the column names, indexed by column number (ie. 1 is the first column).

Lua example

DatabasePrepare ("db", "SELECT * from weapons")

t = DatabaseColumnNames ("db")  --> the names of all columns

Lua notes

Lua returns nil if there are no columns.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnNames)


DatabaseColumns

Script function

world.DatabaseColumns

 Read about scripting

Type

Method

Summary

Find how many columns will be returned by an SQL statement

Prototype

long DatabaseColumns(BSTR DbName);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabasePrepare, to find the number of columns that each row will return. This number might be zero for SQL statements that do not return any data.

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

Return value

A positive integer, or zero,  representing the number of columns that the prepared SQL statement will return.

Otherwise, an error code:

-1 : Database id not found

-2 : Database not open

-4 : Do not have prepared statement

Lua example

columns = DatabaseColumns ("db")

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumns)


DatabaseColumnText

Script function

world.DatabaseColumnText

 Read about scripting

Type

Method

Summary

Returns the contents of an SQL column, as text

Prototype

BSTR DatabaseColumnText(BSTR DbName, long Column);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabaseStep, to get the data in a particular column, converted to text.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Return value

The contents of the column, as a string.

Lua example

x = DatabaseColumnText ("db", 2)  --> the contents of column 2, converted to a text string

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnText)


DatabaseColumnType

Script function

world.DatabaseColumnType

 Read about scripting

Type

Method

Summary

Returns the type of data in an SQL column

Prototype

long DatabaseColumnType(BSTR DbName, long Column);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabaseStep, to find the type of data actually in each column of the current row.

Data types are:

Integer: 1

Float: 2

Text: 3

Blob: 4

Null: 5

This can be called after DatabaseStep to find whether a particular column is text, a number, or NULL (no data).

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Return value

A positive integer  representing the data type of the specified column, as follows:

Integer: 1

Float: 2

Text: 3

Blob: 4

Null: 5

Otherwise, an error code:

-1 : Database id not found

-2 : Database not open

-4 : Do not have prepared statement

-5 : Do not have a valid row

-7 : Column number out of range

Lua example

t = DatabaseColumnType ("db", 2)  --> 3 (if the column is text)

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnType)


DatabaseColumnValue

Script function

world.DatabaseColumnValue

 Read about scripting

Type

Method

Summary

Returns the contents of an SQL column, as text, float, integer, or null

Prototype

VARIANT DatabaseColumnValue(BSTR DbName, long Column);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabaseStep, to get the data in a particular column, in the appropriate format: text, floating point number, integer or null.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Return value

The contents of the column, as a string, long, double or empty variant.

Returns the null variant if there is an error, such as invalid database id, no current row, etc.

Lua example

x = DatabaseColumnValue ("db", 2)  --> the contents of column 2

Lua notes

Lua returns nil for a NULL value.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnValue)


DatabaseColumnValues

Script function

world.DatabaseColumnValues

 Read about scripting

Type

Method

Summary

Returns the contents of all the SQL columns after a step

Prototype

VARIANT DatabaseColumnValues(BSTR DbName);

 View list of data type meanings

Description

You can use this, after successfully doing a DatabaseStep, to get the data in all particular columns, as a table, in the appropriate format: text, floating point number, integer or null.

The table is indexed to start at 1 for the first column, up to the number returned by DatabaseColumns.

Return value

The contents of all columns, as a table. Each item contains a string, long, double or empty variant.

Lua example

t = DatabaseColumnValues ("db")  --> the contents of all columns

Lua notes

Lua returns nil for a NULL value.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseColumnValues)


DatabaseError

Script function

world.DatabaseError

 Read about scripting

Type

Method

Summary

Returns an English string describing the most recent SQL error

Prototype

BSTR DatabaseError(BSTR DbName);

 View list of data type meanings

Description

Call this after one of the other Database routines returns an error code (generally, a code other than 0, 100 or 101).

This will return an explanatory string.

To help with debugging however, codes 100 and 101 also return:

100: "row ready"

101: "finished"

Warning: Since you do not pass the error code into this function, it will not correctly handle the "internal" MUSHclient errors (such as database not open). To handle them correctly you need to test for negative error numbers, as shown in the Lua example below.

Return value

The error message.

Lua example

print (DatabaseError ("db"))

--

---

--- Example of handling internal errors, and SQLite3 errors

---

local MUSHclient_Database_Errors = {

  [-1] = "Database id not found",

  [-2] = "Database not open",

  [-3] = "Already have prepared statement",

  [-4] = "Do not have prepared statement",

  [-5] = "Do not have a valid row",

  [-6] = "Database already exists under a different disk name",

  [-7] = "Column number out of range",

  } -- end of MUSHclient_Database_Errors

-- check for errors on a DatabaseXXXXX call

function dbcheck (code)

 if code == sqlite3.OK or       -- no error

    code == sqlite3.ROW or      -- completed OK with another row of data

    code == sqlite3.DONE then   -- completed OK, no more rows

    return code

  end -- if code OK

  -- DatabaseError won't return the negative errors

  local err = MUSHclient_Database_Errors [code] or DatabaseError(db)

  DatabaseExec (db, "ROLLBACK")  -- rollback any transaction to unlock the database

  error (err, 2)                 -- show error in caller's context

end -- dbcheck

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseError)


DatabaseExec

Script function

world.DatabaseExec

 Read about scripting

Type

Method

Summary

Executes SQL code against an SQLite database

Prototype

long DatabaseExec(BSTR DbName, BSTR Sql);

 View list of data type meanings

Description

This executes SQL on a database previously opened with DatabaseOpen.

You need to supply the database id of an existing opened database, and the SQL statements to be executed. More than one statement may be supplied, separated by semicolons. If one statement causes an error, execution will be terminated. The most recent error message string (if any) can be obtained by calling DatabaseError.

After successful execution, DatabaseExec will return 0. For more explanation if zero is not returned, call DatabaseError.

You cannot call DatabaseExec if you have called DatabasePrepare but not DatabaseFinalize, as a statement is currently being processed.

DatabaseExec is not suitable for executing SQL code that queries the database for data (like a SELECT statement), as there is no provision for getting the results back. In that situation use DatabasePrepare / DatabaseStep / DatabaseFinalize.

To obtain a single row and value, call DatabaseGetField.

Return value

0: Executed OK

-1 : Database id not found

-2 : Database not open

-3 : Already have prepared statement

Lua example

DatabaseOpen ("db", GetInfo (66) .. "mytestdb.sqlite", 6)

DatabaseExec ("db", [[

DROP TABLE IF EXISTS weapons;

CREATE TABLE weapons(

        weapon_id INTEGER NOT NULL PRIMARY KEY autoincrement,

        name  TEXT NOT NULL,

        damage INT default 10,

        weight REAL

      );

      ]])

DatabaseClose ("db")  -- close it

Lua notes

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

-- ---------------------------------

-- Suggested helper functions for handling errors, and fixing up SQL with quotes inside it are:

-- ---------------------------------

local MUSHclient_Database_Errors = {

  [-1] = "Database id not found",

  [-2] = "Database not open",

  [-3] = "Already have prepared statement",

  [-4] = "Do not have prepared statement",

  [-5] = "Do not have a valid row",

  [-6] = "Database already exists under a different disk name",

  [-7] = "Column number out of range",

  } -- end of MUSHclient_Database_Errors

-- check for errors on a DatabaseXXXXX call

function dbcheck (code)

 if code == sqlite3.OK or       -- no error

    code == sqlite3.ROW or      -- completed OK with another row of data

    code == sqlite3.DONE then   -- completed OK, no more rows

    return code

  end -- if code OK

  -- DatabaseError won't return the negative errors

  local err = MUSHclient_Database_Errors [code] or DatabaseError(db)

  DatabaseExec (db, "ROLLBACK")  -- rollback any transaction to unlock the database

  error (err, 2)                 -- show error in caller's context

end -- dbcheck

-- Quote the argument, replacing single quotes with two lots of single quotes.

-- If nil supplied, return NULL (not quoted).

function fixsql (s)

  if s then

    return "'" .. (string.gsub (s, "'", "''")) .. "'"

  else

    return "NULL"

  end -- if

end -- fixsql

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseExec)


DatabaseFinalize

Script function

world.DatabaseFinalize

 Read about scripting

Type

Method

Summary

Finalizes (wraps up) a previously-prepared SQL statement

Prototype

long DatabaseFinalize(BSTR DbName);

 View list of data type meanings

Description

This must be called after calling DatabasePrepare, once you have finished with the current SQL statement. You will not be able to call DatabasePrepare again, until the first one is finalized.

Return value

0: Completed OK

-1 : Database id not found

-2 : Database not open

-4 : Do not have prepared statement

Otherwise an SQLite return code. For example:

1: SQL error or missing database

5 : The database file is locked

21 : Library used incorrectly

Lua example

-- insert a record

DatabasePrepare ("db", "INSERT INTO weapons (name, damage) VALUES ('sword', 42)")  --> returns 0 (sqlite3.OK)

DatabaseStep ("db")   -- returns 101 (sqlite3.DONE)

DatabaseFinalize ("db")  -- returns 0 (sqlite3.OK)

Lua notes

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseFinalize)


DatabaseGetField

Script function

world.DatabaseGetField

 Read about scripting

Type

Method

Summary

Returns a single field from an SQL database

Prototype

VARIANT DatabaseGetField(BSTR Name, BSTR Sql);

 View list of data type meanings

Description

This executes SQL on a database previously opened with DatabaseOpen.

It lets you obtain a single value more easily than doing a DatabasePrepare / DatabaseStep / DatabaseColumnValue / DatabaseFinalize in the cases where you just want to establish a single thing (eg. the count of spells in a table).

You need to supply the database id of an existing opened database, and the SQL statement to be executed.

You cannot call DatabaseGetField if you have called DatabasePrepare but not DatabaseFinalize, as a statement is currently being processed.

The function effectively does this:

DatabasePrepare (Name, Sql)

If unsuccessful, exit with null variant.

Otherwise:

  DatabaseStep (Name)

If successful, and a row was returned, then:

  result = DatabaseColumnValue (Name, 1)

DatabaseFinalize (Name)

If successful, then the value for the first column of the first row is the return value, otherwise the null variant (nil in Lua).

Return value

The contents of the column, as a string, long, double or empty variant.

Returns the null variant if there is an error, such as invalid database id, no current row, etc.

Lua example

DatabaseOpen ("db", GetInfo (82), 1)

value = DatabaseGetField ("db",

                          "SELECT value FROM control WHERE name = 'Version' ")

DatabaseClose ("db")

Lua notes

Returns nil on error.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseGetField)


DatabaseInfo

Script function

world.DatabaseInfo

 Read about scripting

Type

Method

Summary

Returns information about a database

Prototype

VARIANT DatabaseInfo(BSTR DbName, long InfoType);

 View list of data type meanings

Description

This returns information about a particular database.

DbName - the identifying name of an existing database (as supplied to DatabaseOpen). Not the file name.

InfoType - the information you want:

1 - Name of database on disk

2 - Has a DatabasePrepare been validly done recently (and is still active)?

3 - Has a valid row been returned by DatabaseStep?

4 - Count of columns returned from the last DatabasePrepare.

Return value

The specified information about the database, as described above.

An EMPTY variant, if the database does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

DatabaseInfo ("db", 4) --> get count of columns

Lua notes

Lua returns nil instead of a NULL or EMPTY variant.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseInfo)


DatabaseLastInsertRowid

Script function

world.DatabaseLastInsertRowid

 Read about scripting

Type

Method

Summary

Returns the most recently automatically allocated database key

Prototype

BSTR DatabaseLastInsertRowid(BSTR DbName);

 View list of data type meanings

Description

This returns a string which is the most recent automatically allocated database key (for example, if you are using autoincrement on the primary key). Internally it is a 64-bit number, but since there is no ready mechanism for returning 64-bit numbers via the scripting interface, MUSHclient converts it to a string, and returns that.

Return value

A string which is the most recently-allocated key. May be zero if there is no such key.

Lua example

last_key = DatabaseLastInsertRowid ("db")

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseLastInsertRowid)


DatabaseList

Script function

world.DatabaseList

 Read about scripting

Type

Method

Summary

Lists all databases

Prototype

VARIANT DatabaseList();

 View list of data type meanings

Description

This returns a list of all databases created for this world. You could use this to find which databases have been created, and then use DatabaseInfo to find information about each one.

Return value

If there are no databases then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the databases. Use "ubound" to find the number of databases in the list. You can then use "DatabaseInfo" to find details about each database.

Lua example

-- show all databases

databases = DatabaseList()

if databases then

  for _, v in ipairs (databases) do

    Note (v)

  end

end -- if any

Lua notes

Lua returns nil if there are no databases.

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseList)


DatabaseOpen

Script function

world.DatabaseOpen

 Read about scripting

Type

Method

Summary

Opens an SQLite database

Prototype

long DatabaseOpen(BSTR DbName, BSTR Filename, long Flags);

 View list of data type meanings

Description

Opens or creates a database. Databases can be held in memory or on disk. You need read or write permissions to access the database, as it is stored on disk as a normal disk file.

DbName - a unique ID you choose to identify this database for all other operations on it (Eg. "db").

Filename - the file name on disk. The special filename ":memory:" opens an in-memory database. This can be used to manipulate data (or play with SQL) without actually writing to disk.

Flags -

Open_ReadOnly       = 0x00000001

Open_ReadWrite      = 0x00000002

Open_Create         = 0x00000004

Open_DeleteOnClose  = 0x00000008

Open_Exclusive      = 0x00000010

Open_Main_db        = 0x00000100

Open_Temp_db        = 0x00000200

Open_Transient_db   = 0x00000400

Open_Main_Journal   = 0x00000800

Open_Temp_Journal   = 0x00001000

Open_SubJournal     = 0x00002000

Open_Master_Journal = 0x00004000

Open_NoMutex        = 0x00008000

Open_FullMutex      = 0x00010000

Warning - the SQLite documentation suggests that you choose one of:

Open_ReadOnly (1)

Open_ReadWrite (2) or

Open_ReadWrite + Open_Create (6)

If not, the behaviour of the open may be undefined.

Use DatabaseClose to close the database when you are finished with it.

If the database is still open when the world file is closed, the database is automatically closed.

It is not an error to re-open the same database ID of an existing, open, database, provided the disk file name is the same. This will be treated as a no-operation, so that triggers and aliases can open the database without having to check first if it was already open.

Return value

0 : success

-6 : Database already exists under a different disk name

Otherwise, an SQLite error code, and the database ID cannot be used

Lua example

DatabaseOpen ("db",   -- database ID

              GetInfo (66) .. "mytestdb.sqlite",   -- file name

              6)      -- flags

-- do stuff with the database here

DatabaseClose ("db")  -- close it

Lua notes

The Flags parameter can be omitted, and defaults to 6 (Open_ReadWrite + Open_Create).

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseOpen)


DatabasePrepare

Script function

world.DatabasePrepare

 Read about scripting

Type

Method

Summary

Prepares an SQL statement for execution

Prototype

long DatabasePrepare(BSTR DbName, BSTR Sql);

 View list of data type meanings

Description

Prepares (compiles) an SQL statement, ready to be executed with DatabaseStep.

You need to supply the database id of an existing opened database, and the SQL statement to be executed. Only one statement should be supplied. If multiple statements are supplied, only the first will be used. (eg. "drop table a; drop table b" - in this case only the first "drop table" would be executed).

If there is a syntax error in your SQL, that will be reported by a non-zero return code from DatabasePrepare. The most recent error message string (if any) can be obtained by calling DatabaseError.

Note that to include single quotes inside a string literal, in your SQL statement they must be doubled. For example:

INSERT INTO weapons (name, damage) VALUES ('Nick''s sword', 42)

Only one statement can be active at once, so after doing a DatabasePrepare you must do DatabaseFinalize before doing another DatabasePrepare. The exception is that if DatabasePrepare returns an error, then you do not need to do DatabaseFinalize because there is no active statement.

After successfully doing DatabasePrepare, you then need to call DatabaseStep for each row in the query. This is the execution phase. For SQL statements that return multiple rows of data, you need to do DatabaseStep once for each row. For SQL statements that just do one thing (like INSERT INTO) then you only need to call DatabaseStep once.

Also see DatabaseExec if you only need to execute SQL statements (like INSERT INTO) which do not return any results.

Return value

0: Completed OK

-1 : Database id not found

-2 : Database not open

-3 : Already have prepared statement

Otherwise an SQLite return code. For example:

1: SQL error or missing database

5 : The database file is locked

Lua example

-- insert a record

DatabasePrepare ("db", "INSERT INTO weapons (name, damage) VALUES ('sword', 42)")  --> returns 0 (sqlite3.OK)

DatabaseStep ("db")   -- returns 101 (sqlite3.DONE)

DatabaseFinalize ("db")  -- returns 0 (sqlite3.OK)

-- see the DatabaseStep entry for a more elaborate example.

-- A suitable function for fixing up strings is this:

-- Quote the argument, replacing single quotes with two lots of single quotes.

-- If nil supplied, return NULL (not quoted).

function fixsql (s)

  if s then

    return "'" .. (string.gsub (s, "'", "''")) .. "'"

  else

    return "NULL"

  end -- if

end -- fixsql

Lua notes

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabasePrepare)


DatabaseReset

Script function

world.DatabaseReset

 Read about scripting

Type

Method

Summary

Resets a previously-prepared SQL statement to the start

Prototype

long DatabaseReset(BSTR DbName);

 View list of data type meanings

Description

Resets a previously-prepared SQL statement to start iterating again from the beginning.

Return value

0: Completed OK

-1 : Database id not found

-2 : Database not open

-4 : Do not have prepared statement

Otherwise an SQLite return code. For example:

1: SQL error or missing database

5 : The database file is locked

21 : Library used incorrectly

Lua example

DatabaseReset ("db")   -- back to the start

Lua notes

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseStep (Executes a previously-prepared SQL statement)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseReset)


DatabaseStep

Script function

world.DatabaseStep

 Read about scripting

Type

Method

Summary

Executes a previously-prepared SQL statement

Prototype

long DatabaseStep(BSTR DbName);

 View list of data type meanings

Description

Executes an SQL statement over one row over the database. In the case of a SELECT statement, one row is returned for each call to DatabaseStep.

After successfully doing DatabasePrepare, you then need to call DatabaseStep for each row in the query. This is the execution phase. For SQL statements that return multiple rows of data, you need to do DatabaseStep once for each row. For SQL statements that just do one thing (like INSERT INTO) then you only need to call DatabaseStep once.

DatabaseStep will return SQLITE_ROW (100) if it has returned a row of data, otherwise it will return SQLITE_DONE (101) if it has reached the end of the query. You could make a loop that continues to call DatabaseStep until it no longer returns 100, in order to process every row in the query.

If you want to reprocess the SQL query from the start for some reason, you can call DatabaseReset and the query restarts at the beginning (you would then need to call DatabaseStep again to re-obtain the first row).

Return value

100: Another row is ready.

101: Completed OK, no further rows.

-1 : Database id not found

-2 : Database not open

-4 : Do not have prepared statement

Otherwise an SQLite return code. For example:

1: SQL error or missing database

5 : The database file is locked

21 : Library used incorrectly

Lua example

require "tprint"

DatabaseOpen ("db", GetInfo (66) .. "mytestdb.sqlite", 6)

rc = DatabaseExec ("db", [[

DROP TABLE IF EXISTS weapons;

CREATE TABLE weapons(

        weapon_id INTEGER NOT NULL PRIMARY KEY autoincrement,

        name  TEXT NOT NULL,

        damage INT default 10,

        weight REAL

      );

      ]])

-- put some data into the database

DatabaseExec ("db",

  [[

  INSERT INTO weapons (name, damage) VALUES ('sword', 42);

  INSERT INTO weapons (name, damage) VALUES ('mace', 55);

  INSERT INTO weapons (name, damage) VALUES ('staff', 35);

  ]])

-- prepare a query

DatabasePrepare ("db", "SELECT * from weapons ORDER BY name")

-- find the column names

names = DatabaseColumnNames ("db")

tprint (names)

-- execute to get the first row

rc = DatabaseStep ("db")  -- read first row

-- now loop, displaying each row, and getting the next one

while rc == sqlite3.ROW do

  print ("")

  values = DatabaseColumnValues ("db")

  tprint (values)

  rc = DatabaseStep ("db")  -- read next row

end -- while loop

-- finished with the statement

DatabaseFinalize ("db")

DatabaseClose ("db")  -- close it

Lua notes

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0

sqlite3.INTEGER = 1

sqlite3.INTERNAL = 2

sqlite3.PERM = 3

sqlite3.ABORT = 4

sqlite3.BUSY = 5

sqlite3.LOCKED = 6

sqlite3.NOMEM = 7

sqlite3.READONLY = 8

sqlite3.INTERRUPT = 9

sqlite3.IOERR = 10

sqlite3.CORRUPT = 11

sqlite3.NOTFOUND = 12

sqlite3.FULL = 13

sqlite3.CANTOPEN = 14

sqlite3.PROTOCOL = 15

sqlite3.EMPTY = 16

sqlite3.SCHEMA = 17

sqlite3.TOOBIG = 18

sqlite3.CONSTRAINT = 19

sqlite3.MISMATCH = 20

sqlite3.MISUSE = 21

sqlite3.NOLFS = 22

sqlite3.FORMAT = 24

sqlite3.RANGE = 25

sqlite3.NOTADB = 26

sqlite3.ROW = 100

sqlite3.DONE = 101

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseTotalChanges (Returns a count of the total changes to the database)

(Help topic: function=DatabaseStep)


DatabaseTotalChanges

Script function

world.DatabaseTotalChanges

 Read about scripting

Type

Method

Summary

Returns a count of the total changes to the database

Prototype

long DatabaseTotalChanges(BSTR DbName);

 View list of data type meanings

Description

This function returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened. The count includes all changes from all trigger contexts. However, the count does not include changes used to implement REPLACE constraints, do rollbacks or ABORT processing, or DROP table processing. The changes are counted as soon as the statement that makes them is completed (when the statement handle is passed to DatabaseReset or DatabaseFinalize).

Return value

A positive integer, or zero, indicating the count of changes.

Otherwise:

-1 : Database id not found

-2 : Database not open

Lua example

changes = DatabaseTotalChanges ("db")

See Also ...

Topics

 Database (SQLite)

 Lua SQLite (database) interface

 Scripting

Functions

 DatabaseChanges (Returns a count of the changes to the database by the most recent SQL statement)

 DatabaseClose (Closes an SQLite database)

 DatabaseColumnName (Find the name of a specified column returned by an SQL statement)

 DatabaseColumnNames (Return a table of all the columns returned by an SQL statement)

 DatabaseColumns (Find how many columns will be returned by an SQL statement)

 DatabaseColumnText (Returns the contents of an SQL column, as text)

 DatabaseColumnType (Returns the type of data in an SQL column)

 DatabaseColumnValue (Returns the contents of an SQL column, as text, float, integer, or null)

 DatabaseColumnValues (Returns the contents of all the SQL columns after a step)

 DatabaseError (Returns an English string describing the most recent SQL error)

 DatabaseExec (Executes SQL code against an SQLite database)

 DatabaseFinalize (Finalizes (wraps up) a previously-prepared SQL statement)

 DatabaseGetField (Returns a single field from an SQL database)

 DatabaseInfo (Returns information about a database)

 DatabaseLastInsertRowid (Returns the most recently automatically allocated database key)

 DatabaseList (Lists all databases)

 DatabaseOpen (Opens an SQLite database)

 DatabasePrepare (Prepares an SQL statement for execution)

 DatabaseReset (Resets a previously-prepared SQL statement to the start)

 DatabaseStep (Executes a previously-prepared SQL statement)

(Help topic: function=DatabaseTotalChanges)


Debug

Script function

world.Debug

 Read about scripting

Type

Method

Summary

Displays debugging information about the world

Prototype

VARIANT Debug(BSTR Command);

 View list of data type meanings

Description

You can use this to quickly list things of interest about the world.

You can currently get the following information:

"actions" - things like hyperlinks that do something

"aliases" - list of world aliases

"alpha_options" - the world's alpha (string) options, and their values

"ansi" - lists the ANSI colours defined in the ANSI configuration tab (with swatches)

"arrays" - list of world arrays (see ArrayCreate)

"colours" - known colour names, (with swatches) and RGB codes etc.

"colours256" - list of extended ANSI colours (with swatches)

"commands" - lists command history

"custom_colours - lists the 16 custom colours along with their names (with swatches)

"entities" - lists known MXP entities with what the translate to

"global_options" - list of global options and their values

"included_options" - list of options set by included files

"info" - lists all GetInfo items and associated values

"internal_commands" - lists commands that can be done with DoCommand

"options" - the world's numeric options, and their values

"option_info" - list of alpha/numeric options and their ranges

"plugins" - lists information for each plugin (aliases, triggers, etc.)

"server_elements" - lists MXP elements defined by the MUD server

"server_entities" - lists MXP entities defined by the MUD server

"summary" - summarizes triggers, aliases, world info, plugins, miniwindows

"triggers" - list of world triggers

"variables" - list of world variables

eg. /world.Debug "aliases"

To find the list without referring to this web page, just type:

/world.Debug ""

Return value

Returns a variant, however it is not used at present. The debug information is displayed in the world window.

Lua example

Debug ("colours")

Jscript example

/world.Debug ("colours");

PerlScript example

/$world->Debug ("colours");

Python example

world.Debug ("colours")

VBscript example

/world.Debug "colours"

See Also ...

Topic

 Information

Functions

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 Simulate (Simulate input from the MUD, for debugging purposes)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=Debug)


DeleteAlias

Script function

world.DeleteAlias

 Read about scripting

Type

Method

Summary

Deletes an alias

Prototype

long DeleteAlias(BSTR AliasName);

 View list of data type meanings

Description

Deletes the named alias from the list of aliases.

WARNING - if the alias is executing a script it cannot be deleted. For example, an alias cannot delete itself.

If you need to delete an alias from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableGroup to disable it first.

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasNotFound: The named alias does not exist

eItemInUse: Cannot delete trigger/alias/timer because it is executing a script

eOK: deleted OK

 View list of return code meanings

Lua example

DeleteAlias("my_alias")

Jscript example

world.DeleteAlias("my_alias");

PerlScript example

$world->DeleteAlias("my_alias");

Python example

world.DeleteAlias("my_alias")

VBscript example

world.DeleteAlias "my_alias"

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=DeleteAlias)


DeleteAliasGroup

Script function

world.DeleteAliasGroup

 Read about scripting

Type

Method

Summary

Deletes a group of aliases

Prototype

long DeleteAliasGroup(BSTR GroupName);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of aliases do this:

  world.DeleteAliasGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount

  mycount = world.DeleteAliasGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the alias is executing a script it cannot be deleted. For example, an alias cannot delete itself.

If you need to delete an alias from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableAliasGroup to disable it first.

Since DeleteAliasGroup deletes multiple aliases, any found to be "in use" (that is, executing a script) will not be deleted.

Return value

A count of the number of items deleted.

Lua example

DeleteAliasGroup ("groupname")

Jscript example

world.DeleteAliasGroup ("groupname");

PerlScript example

$world->DeleteAliasGroup ("groupname");

Python example

world.DeleteAliasGroup ("groupname")

VBscript example

world.DeleteAliasGroup "groupname"

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTriggerGroup (Deletes a group of triggers)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 GetTimerInfo (Gets details about a timer)

 GetTriggerInfo (Gets details about a named trigger)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=DeleteAliasGroup)


DeleteAllMapItems

Script function

world.DeleteAllMapItems

 Read about scripting

Type

Method

Summary

Deletes the all items from the auto-mapper sequence.

Prototype

long DeleteAllMapItems();

 View list of data type meanings

Description

Deletes all items from the auto-mapper sequence.

You can use this to start a new auto-map sequence.

Return value

eNoMapItems: Map sequence was empty, nothing was deleted.

eOK: Deleted all items

 View list of return code meanings

Lua example

DeleteAllMapItems()

Jscript example

world.DeleteAllMapItems();

PerlScript example

$world->DeleteAllMapItems();

Python example

world.DeleteAllMapItems

VBscript example

world.DeleteAllMapItems

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=DeleteAllMapItems)


DeleteCommandHistory

Script function

world.DeleteCommandHistory

 Read about scripting

Type

Method

Summary

Deletes command history list.

Prototype

void DeleteCommandHistory();

 View list of data type meanings

Description

Deletes any commands in the command history list for all windows. If you have multiple windows open to this world all comand histories will be deleted.  There is no confirmation dialog.

Return value

Nothing.

Lua example

DeleteCommandHistory()

Jscript example

world.DeleteCommandHistory();

PerlScript example

$world->DeleteCommandHistory();

Python example

world.DeleteCommandHistory

VBscript example

world.DeleteCommandHistory

See Also ...

Function

 DeleteOutput (Clears all output from the output window.)

(Help topic: function=DeleteCommandHistory)


DeleteGroup

Script function

world.DeleteGroup

 Read about scripting

Type

Method

Summary

Deletes a group of triggers, aliases and timers

Prototype

long DeleteGroup(BSTR GroupName);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of triggers, aliases and timers do this:

  world.DeleteGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount

  mycount = world.DeleteGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

Return value

A count of the number of items deleted.

Lua example

DeleteGroup ("groupname")

Jscript example

world.DeleteGroup ("groupname");

PerlScript example

$world->DeleteGroup ("groupname");

Python example

world.DeleteGroup ("groupname")

VBscript example

world.DeleteGroup "groupname"

See Also ...

Topics

 Aliases

 Groups

 Timers

 Triggers

Functions

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAliasInfo (Gets details about an alias)

 GetTimerInfo (Gets details about a timer)

 GetTriggerInfo (Gets details about a named trigger)

(Help topic: function=DeleteGroup)


DeleteLastMapItem

Script function

world.DeleteLastMapItem

 Read about scripting

Type

Method

Summary

Deletes the most recently-added item from the auto-mapper sequence.

Prototype

long DeleteLastMapItem();

 View list of data type meanings

Description

Deletes the most recently-added item from the auto-mapper sequence. You might use this in a trigger to remove a direction that you were not able to go.

Return value

eNoMapItems: Map sequence was empty, nothing was deleted.

eOK: Deleted last entry

 View list of return code meanings

Lua example

DeleteLastMapItem()

Jscript example

world.DeleteLastMapItem();

PerlScript example

$world->DeleteLastMapItem();

Python example

world.DeleteLastMapItem

VBscript example

world.DeleteLastMapItem

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=DeleteLastMapItem)


DeleteLines

Script function

world.DeleteLines

 Read about scripting

Type

Method

Summary

Clears some recent lines from the output window.

Prototype

void DeleteLines(long Count);

 View list of data type meanings

Description

Clears 'Count' lines from the output window, starting at the end (most recently-displayed).

This allows you to script the omission of recently-received lines (for example, in a multi-line trigger).

All line types are omitted (whether received from the MUD, command input, or Note lines). A line is counted as a physical line on the screen, it does not necessarily end in a newline character.

Warning - do NOT call DeleteLines from a trigger, alias or timer using send-to-script. For design reasons this will not work. In version 3.76 you will cause the client to crash if you do this. In version 3.77 upwards it will silently fail (ie. do nothing).

If you want to call DeleteLines from a trigger you must call a function in your script file (or plugin script), not directly from send-to-script.

You can also not call it from a plugin callback.

Return value

Nothing.

Lua example

DeleteLines(10)

Jscript example

world.DeleteLines(10);

PerlScript example

$world->DeleteLines(10);

Python example

world.DeleteLines (10)

VBscript example

world.DeleteLines (10)

See Also ...

Function

 DeleteOutput (Clears all output from the output window.)

(Help topic: function=DeleteLines)


DeleteOutput

Script function

world.DeleteOutput

 Read about scripting

Type

Method

Summary

Clears all output from the output window.

Prototype

void DeleteOutput();

 View list of data type meanings

Description

Clears all output from the output window. There is no confirmation dialog.

To delete part of the output buffer only, see DeleteLines.

Return value

Nothing.

Lua example

DeleteOutput()

Jscript example

world.DeleteOutput();

PerlScript example

$world->DeleteOutput();

Python example

world.DeleteOutput

VBscript example

world.DeleteOutput

See Also ...

Functions

 DeleteCommandHistory (Deletes command history list.)

 DeleteLines (Clears some recent lines from the output window.)

(Help topic: function=DeleteOutput)


DeleteTemporaryAliases

Script function

world.DeleteTemporaryAliases

 Read about scripting

Type

Method

Summary

Deletes all temporary aliases

Prototype

long DeleteTemporaryAliases();

 View list of data type meanings

Description

Deletes all aliases marked as "temporary".

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary aliases are not loaded from the world file).

Return value

Returns a count of the number of aliases deleted.

Lua example

DeleteTemporaryAliases ()

Jscript example

world.DeleteTemporaryAliases ();

PerlScript example

$world->DeleteTemporaryAliases ();

Python example

world.DeleteTemporaryAliases

VBscript example

world.DeleteTemporaryAliases

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=DeleteTemporaryAliases)


DeleteTemporaryTimers

Script function

world.DeleteTemporaryTimers

 Read about scripting

Type

Method

Summary

Deletes all temporary timers

Prototype

long DeleteTemporaryTimers();

 View list of data type meanings

Description

Deletes all timers marked as "temporary".

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary timers are not loaded from the world file).

You might also use this if a runaway script created too many temporary timers with "DoAfter" or similar.

Return value

Returns a count of the number of timers deleted.

Lua example

DeleteTemporaryTimers ()

Jscript example

world.DeleteTemporaryTimers ();

PerlScript example

$world->DeleteTemporaryTimers ();

Python example

world.DeleteTemporaryTimers

VBscript example

world.DeleteTemporaryTimers

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DeleteTemporaryTimers)


DeleteTemporaryTriggers

Script function

world.DeleteTemporaryTriggers

 Read about scripting

Type

Method

Summary

Deletes all temporary triggers

Prototype

long DeleteTemporaryTriggers();

 View list of data type meanings

Description

Deletes all triggers marked as "temporary".

The intention here is to provide a quick way of restoring the world to how it would be after loading (since temporary triggers are not loaded from the world file).

Return value

Returns a count of the number of triggers deleted.

Lua example

DeleteTemporaryTriggers ()

Jscript example

world.DeleteTemporaryTriggers ();

PerlScript example

$world->DeleteTemporaryTriggers ();

Python example

world.DeleteTemporaryTriggers

VBscript example

world.DeleteTemporaryTriggers

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=DeleteTemporaryTriggers)


DeleteTimer

Script function

world.DeleteTimer

 Read about scripting

Type

Method

Summary

Deletes a timer

Prototype

long DeleteTimer(BSTR TimerName);

 View list of data type meanings

Description

Deletes the named timer from the list of timers.

WARNING - if the timer is executing a script it cannot be deleted. For example, a timer cannot delete itself.

If you need to delete a timer from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTimer to disable it first.

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerNotFound: The named timer does not exist

eItemInUse: Cannot delete trigger/alias/timer because it is executing a script

eOK: deleted OK

 View list of return code meanings

Lua example

DeleteTimer("mytimer")

Jscript example

world.DeleteTimer("mytimer");

PerlScript example

$world->DeleteTimer("mytimer");

Python example

world.DeleteTimer("mytimer")

VBscript example

world.DeleteTimer "mytimer"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DeleteTimer)


DeleteTimerGroup

Script function

world.DeleteTimerGroup

 Read about scripting

Type

Method

Summary

Deletes a group of timers

Prototype

long DeleteTimerGroup(BSTR GroupName);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of timers do this:

  world.DeleteTimerGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount

  mycount = world.DeleteTimerGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the timer is executing a script it cannot be deleted. For example, a timer cannot delete itself.

If you need to delete a timer from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTimerGroup to disable it first.

Since DeleteTimerGroup deletes multiple timers, any found to be "in use" (that is, executing a script) will not be deleted.

Return value

A count of the number of items deleted.

Lua example

DeleteTimerGroup ("groupname")

Jscript example

world.DeleteTimerGroup ("groupname");

PerlScript example

$world->DeleteTimerGroup ("groupname");

Python example

world.DeleteTimerGroup ("groupname")

VBscript example

world.DeleteTimerGroup "groupname"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTriggerGroup (Deletes a group of triggers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAliasInfo (Gets details about an alias)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 GetTriggerInfo (Gets details about a named trigger)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DeleteTimerGroup)


DeleteTrigger

Script function

world.DeleteTrigger

 Read about scripting

Type

Method

Summary

Deletes a trigger

Prototype

long DeleteTrigger(BSTR TriggerName);

 View list of data type meanings

Description

Deletes the named trigger from the list of triggers.

WARNING - if the trigger is executing a script it cannot be deleted. For example, a trigger cannot delete itself.

If you need to delete a trigger from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTrigger to disable it first.

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerNotFound: The named trigger does not exist

eItemInUse: The trigger is currently executing a script

eOK: deleted OK

 View list of return code meanings

Lua example

DeleteTrigger("my_trigger")

Jscript example

world.DeleteTrigger("my_trigger");

PerlScript example

$world->DeleteTrigger("my_trigger");

Python example

world.DeleteTrigger("my_trigger")

VBscript example

world.DeleteTrigger "my_trigger"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTriggerGroup (Deletes a group of triggers)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=DeleteTrigger)


DeleteTriggerGroup

Script function

world.DeleteTriggerGroup

 Read about scripting

Type

Method

Summary

Deletes a group of triggers

Prototype

long DeleteTriggerGroup(BSTR GroupName);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To delete an entire group of triggers do this:

  world.DeleteTriggerGroup "groupname"

For debugging purposes the function returns a count of the number of members deleted. eg.

  dim mycount

  mycount = world.DeleteTriggerGroup ("groupname")

If you are using plugins only the members of the current plugin (if any) are deleted. If the call is made outside a plugin only the members of the group that are not in a plugin are deleted.

WARNING - if the trigger is executing a script it cannot be deleted. For example, a trigger cannot delete itself.

If you need to delete a trigger from within itself use DoAfterSpecial to delete it after a short delay. You might also want to use EnableTriggerGroup to disable it first.

Since DeleteTriggerGroup deletes multiple triggers, any found to be "in use" (that is, executing a script) will not be deleted.

Return value

A count of the number of items deleted.

Lua example

DeleteTriggerGroup ("groupname")

Jscript example

world.DeleteTriggerGroup ("groupname");

PerlScript example

$world->DeleteTriggerGroup ("groupname");

Python example

world.DeleteTriggerGroup ("groupname")

VBscript example

world.DeleteTriggerGroup "groupname"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTrigger (Deletes a trigger)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAliasInfo (Gets details about an alias)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTimerInfo (Gets details about a timer)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=DeleteTriggerGroup)


DeleteVariable

Script function

world.DeleteVariable

 Read about scripting

Type

Method

Summary

Deletes a variable

Prototype

long DeleteVariable(BSTR VariableName);

 View list of data type meanings

Description

Deletes the named variable.

Return value

eInvalidObjectLabel: The alias name is not valid

eVariableNotFound: The variable does not exist

eOK: deleted OK

 View list of return code meanings

Lua example

DeleteVariable("myvariable")

Jscript example

world.DeleteVariable("myvariable");

PerlScript example

$world->DeleteVariable("myvariable");

Python example

world.DeleteVariable("myvariable")

VBscript example

world.DeleteVariable "myvariable"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: function=DeleteVariable)


DiscardQueue

Script function

world.DiscardQueue

 Read about scripting

Type

Method

Summary

Discards the speed walk queue

Prototype

long DiscardQueue();

 View list of data type meanings

Description

Discards any commands queued up, to be sent at the speedwalk delay interval.

The return value is the number of commands discarded.

Return value

The number of commands discarded (might be zero).

Lua example

DiscardQueue()

Jscript example

world.discardqueue();

PerlScript example

$world->discardqueue();

Python example

world.discardqueue

VBscript example

world.discardqueue

See Also ...

Functions

 GetQueue (Returns a variant array which is a list of queued commands)

 Queue (Queues a command for sending at the "speed walk" rate.)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=DiscardQueue)


Disconnect

Script function

world.Disconnect

 Read about scripting

Type

Method

Summary

Disconnects the world from the MUD server

Prototype

long Disconnect();

 View list of data type meanings

Description

This disconnects from the current world. (ie. It disconnects from the MUD server).

Return value

eWorldClosed: world is already closed

eOK: disconnected OK

 View list of return code meanings

Lua example

Disconnect()

Jscript example

world.disconnect();

PerlScript example

$world->disconnect();

Python example

world.disconnect

VBscript example

world.disconnect

See Also ...

Functions

 Connect (Connects the world to the MUD server)

 IsConnected (Tests to see if the world is connected to the MUD server)

(Help topic: function=Disconnect)


DoAfter

Script function

world.DoAfter

 Read about scripting

Type

Method

Summary

Adds a one-shot, temporary timer - simplified interface

Prototype

long DoAfter(double Seconds, BSTR SendText);

 View list of data type meanings

Description

This routine adds an unlabelled, temporary, one-shot timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to  86,399).

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

You can also use DoAfterSpeedWalk - this is the same as DoAfter, except the command is interpreted as a speedwalk sequence.

You can also use DoAfterNote - this is the same as DoAfter, except the text is sent to the output window, not the MUD.

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.

WARNING - as DoAfter is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfter is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

Return value

eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399).

eOK: added OK

 View list of return code meanings

Lua example

DoAfter (10, "eat food")

DoAfter (20.5, "get bottle bag")

DoAfter (21, "drink water")

Jscript example

world.DoAfter (10, "eat food");

world.DoAfter (20.5, "get bottle bag");

world.DoAfter (21, "drink water");

PerlScript example

$world->DoAfter (10, "eat food");

$world->DoAfter (20.5, "get bottle bag");

$world->DoAfter (21, "drink water");

Python example

world.DoAfter (10, "eat food")

world.DoAfter (20.5, "get bottle bag")

world.DoAfter (21, "drink water")

VBscript example

world.DoAfter 10, "eat food"

world.DoAfter 20.5, "get bottle bag"

world.DoAfter 21, "drink water"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DoAfter)


DoAfterNote

Script function

world.DoAfterNote

 Read about scripting

Type

Method

Summary

Adds a one-shot, temporary note timer - simplified interface

Prototype

long DoAfterNote(long Seconds, BSTR NoteText);

 View list of data type meanings

Description

This routine adds an unlabelled, temporary, one-shot note timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399).

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

When the time elapses the text will be "noted" - that is, displayed in the output window, not sent to the MUD.

You can also use DoAfter if you wish to send to the world.

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.

WARNING - as DoAfterNote is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterNote is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

Return value

eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399).

eOK: added OK

 View list of return code meanings

Lua example

DoAfterNote (60, "Spell has worn off!")

Jscript example

world.DoAfterNote (60, "Spell has worn off!");

PerlScript example

$world->DoAfterNote (60, "Spell has worn off!");

Python example

world.DoAfterNote (60, "Spell has worn off!")

VBscript example

world.DoAfterNote 60, "Spell has worn off!"

See Also ...

Topic

 Notes

Functions

 AddTimer (Adds a timer)

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=DoAfterNote)


DoAfterSpecial

Script function

world.DoAfterSpecial

 Read about scripting

Type

Method

Summary

Adds a one-shot, temporary, timer to carry out some special action

Prototype

long DoAfterSpecial(long Seconds, BSTR SendText, short SendTo);

 View list of data type meanings

Description

This routine adds an unlabelled, temporary, one-shot timer, set to go off after

the designated number of seconds.

The timer sends its "SendText" text to the designated location when it fires.

The first argument (seconds) must evaluate to a time between 0.1 second,

and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399).

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

The purpose of this is simplify the frequent case of simply wanting to do

something in a few seconds, rather than using AddTimer.

This lets you do things that involve simple scripting at some future time,

without having to go to a lot of trouble writing script routines.

The "SendTo" argument specifies where the text is to be sent to when the

time elapsed. It can be one of:

0: World

1: Command window

2: Output window

3: Status line

4: Notepad (new)

5: Notepad (append)

6: Log File

7: Notepad (replace)

8: Command queue

9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit (send to script engine, after lines have been omitted)

The case "set variable" is not very useful because there is no way of specifying which variable,

however instead you could use "send to script" (12) and do a "setvariable". eg.

world.DoAfterSpecial 5, "SetVariable ""target"", ""kobold"" ", 12

This example uses double-quotes for the variable name and variable value, because they are quotes

within quotes (an argument to SetVariable inside the argument to DoAfterSpecial).

Also, case "Script - after omit" is really intended for use in triggers, and will have the same behaviour as "Script" if used elsewhere.

WARNING - as DoAfterSpecial is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterSpecial is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

Return value

eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399).

eOptionOutOfRange: The "SendTo" argument is not in the range 0 to 12.

eOK: added OK

 View list of return code meanings

Lua example

DoAfterSpecial (5, 'EnableTriggerGroup ("mygroup", 1)', sendto.script)

--[[

In the above example the last argument (sendto.script) means send the

command to the script engine after 5 seconds.

The argument to EnableTriggerGroup has the alternative quotes,

because it is quotes within quotes.

--]]

DoAfterSpecial (10, "4s 3w", sendto.speedwalk)

Lua notes

The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

world.DoAfterSpecial (5, "EnableTriggerGroup ("mygroup", 1);", 12);

In the above example the last argument (12) means send the

command to the script engine after 5 seconds.

The argument to EnableTriggerGroup has escaped quotes,

because it is quotes within quotes.

world.DoAfterSpecial (10, "4s 3w", 11);

PerlScript example

$world->DoAfterSpecial (5, 'EnableTriggerGroup ("mygroup", 1);', 12);

In the above example the last argument (12) means send the

command to the script engine after 5 seconds.

We use single quotes for the argument to DoAfterSpecial,

so we can use double quotes for the argument to EnableTriggerGroup.

$world->DoAfterSpecial (10, "4s 3w", 11);

Python example

world.DoAfterSpecial (5, "EnableTriggerGroup ("mygroup", 1)", 12)

In the above example the last argument (12) means send the

command to the script engine after 5 seconds.

The argument to EnableTriggerGroup has escaped quotes,

because it is quotes within quotes.

world.DoAfterSpecial (10, "4s 3w", 11)

VBscript example

world.DoAfterSpecial 5, "EnableTriggerGroup ""mygroup"", 1", 12

In the above example the last argument (12) means send the

command to the script engine after 5 seconds.

The argument to EnableTriggerGroup has double quotes,

because it is quotes within quotes.

world.DoAfterSpecial 10, "4s 3w", 11

In the above example the last argument (11) means send the command

to the speed walk parser after 10 seconds.

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DoAfterSpecial)


DoAfterSpeedWalk

Script function

world.DoAfterSpeedWalk

 Read about scripting

Type

Method

Summary

Adds a one-shot, temporary speedwalk timer - simplified interface

Prototype

long DoAfterSpeedWalk(long Seconds, BSTR SendText)

 View list of data type meanings

Description

This routine adds an unlabelled, temporary, one-shot speedwalk timer, set to go off after the designated number of seconds. The first argument (seconds) must evaluate to a time between 0.1 second, and 23 hours 59 minutes 59 seconds (that is, 0.1 to 86,399).

From version 3.61 onwards of MUSHclient the interval may include fractions (ie. it is a floating-point number). This lets you set up sub-second intervals (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the 'Timer Interval' in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds. In other words, regardless of what you specify, the timers are only checked every 10th of a second.

You can also use DoAfter if you do not wish to speed walk, or DoAfterNote if you want to send a note to the output window.

The purpose of this is simplify the frequent case of simply wanting to do something in a few seconds, rather than using AddTimer.

WARNING - as DoAfterSpeedWalk is implemented by using temporary MUSHclient timers, it will not work if timers are disabled. If DoAfterSpeedWalk is not working for you (however the function call is returning zero) then ensure that timers are enabled in the Timers configuration dialog.

Return value

eTimeInvalid: The time is invalid (seconds not in range 0.1 to 86,399).

eOK: added OK

 View list of return code meanings

Lua example

DoAfterSpeedWalk (10, "5e 4s w")

Jscript example

world.DoAfterSpeedWalk (10, "5e 4s w");

PerlScript example

$world->DoAfterSpeedWalk (10, "5e 4s w");

Python example

world.DoAfterSpeedWalk (10, "5e 4s w")

VBscript example

world.DoAfterSpeedWalk 10, "5e 4s w"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=DoAfterSpeedWalk)


DoCommand

Script function

world.DoCommand

 Read about scripting

Type

Method

Summary

Queues a MUSHclient menu command

Prototype

long DoCommand(BSTR Command);

 View list of data type meanings

Description

Queues an internal MUSHclient command, as if you had selected it from the menu or typed the corresponding keyboard accelerator. This lets you script things that are available from menus but might not be provided for directly in the scripting language (eg. connect to worlds in startup list).

The command is actually entered in the Windows message queue using the PostMessage operating-system call. What this means is that the command you specify is not done immediately, but will be actioned next time through the main "message loop".

The reason for this is that some commands (eg. world.DoCommand "close", or world.DoCommand "ExitClient") would crash the client because the program (or window) would close while the script was still executing. Similarly any command that opened a dialog box would mean that the script would be paused until the dialog box was closed.

That means that this sort of thing will *not* work:

world.DoCommand "copy"

mystring = world.GetClipboard

This is because the copy command is deferred until later, whereas the GetClipboard is executed immediately (as it is an inbuilt script command).

The intention of DoCommand is that you can bind aliases to internal commands, or automate some actions, but not to directly execute MUSHclient actions while a script is running. For instance, you might make an alias:

Alias: #chats

Send:  DoCommand "chatsessions"

Send to: Script

To find the current list of commands you can use:

/world.Debug "internal_commands"

Also see world.GetInternalCommandsList to get the list in a script.

The current list is (as at version 3.73):

ASCIIart, About, ActivateInputArea, ActivityList, ActivityToolbar,

ActivityViewCloseWorld, ActivityViewSaveWorld, ActivityViewSaveWorldAs, AltA,

AltB, AltDownArrow, AltJ, AltK, AltL, AltM, AltN, AltO, AltP, AltQ, AltR,

AltS, AltT, AltU, AltUpArrow, AltV, AltX, AltY, AltZ, AlwaysOnTop,

ArrangeIcons, AutoConnect, AutoSay, Base64Decode, Base64Encode,

BookmarkSelection, BugReports, CascadeWindows, ChatSessions,

ClearCommandHistory, ClearOutput, Close, CloseAllNotepadWindows, ColourPicker,

CommandEnd, CommandHistory, CommandHome, CompleteFunction, ConfigureAliases,

ConfigureAutosay, ConfigureChat, ConfigureColours, ConfigureCommands,

ConfigureCustomColours, ConfigureKeypad, ConfigureLogging, ConfigureMacros,

ConfigureMudaddress, ConfigureMxpPueblo, ConfigureNameAndPassword,

ConfigureNotes, ConfigureOutput, ConfigurePasteToWorld, ConfigurePrinting,

ConfigureScripting, ConfigureSendFile, ConfigureTimers, ConfigureTriggers,

ConfigureVariables, Connect, ConnectToAllOpenWorlds,

ConnectToWorldsInStartupList, Connect_Or_Reconnect, ContextHelp,

ConvertHTMLspecial, Copy, CopyAsHTML, CtrlKeypad0, CtrlKeypad1, CtrlKeypad2,

CtrlKeypad3, CtrlKeypad4, CtrlKeypad5, CtrlKeypad6, CtrlKeypad7, CtrlKeypad8,

CtrlKeypad9, CtrlKeypadDash, CtrlKeypadDot, CtrlKeypadPlus, CtrlKeypadSlash,

CtrlKeypadStar, CtrlN, CtrlP, CtrlZ, Cut, DebugIncomingPackets,

DebugWorldInput, DiscardQueuedCommands, Disconnect, DoMapperComment,

DoMapperSpecial, DosToMac, DosToUnix, East, EditScriptFile, End, Examine,

ExitClient, Find, FindAgain, FindNextNotepad, FindNotepad, FlipToNotepad,

Forum, FreezeOutput, FullScreenMode, FunctionList, FunctionsWebPage,

GenerateCharacterName, GenerateUniqueID, GettingStarted, GlobalPreferences,

GlobalReplace, GoToBookmark, GoToLine, GoToMatchingBrace, GoToNotepadLine,

GoToURL, Help, HelpContents, HelpIndex, HighlightWord, Immediate, Import,

Info, InfoBar, InputGlobalChange, InsertDateTime, Keypad0, Keypad1, Keypad2,

Keypad3, Keypad4, Keypad5, Keypad6, Keypad7, Keypad8, Keypad9, KeypadDash,

KeypadDot, KeypadPlus, KeypadSlash, KeypadStar, KeysEscape, KeysTab, LineDown,

LineUp, LogSession, Look, LowerCase, MacToDos, MacroCtrlF1, MacroCtrlF10,

MacroCtrlF11, MacroCtrlF12, MacroCtrlF2, MacroCtrlF3, MacroCtrlF5, MacroCtrlF

6, MacroCtrlF7, MacroCtrlF8, MacroCtrlF9, MacroF1, MacroF10, MacroF11, MacroF

12, MacroF2, MacroF3, MacroF4, MacroF5, MacroF6, MacroF7, MacroF8, MacroF9,

MacroShiftF1, MacroShiftF10, MacroShiftF11, MacroShiftF12, MacroShiftF2,

MacroShiftF3, MacroShiftF4, MacroShiftF5, MacroShiftF6, MacroShiftF7,

MacroShiftF8, MacroShiftF9, MakeMultiLineTrigger, Mapper, Maximize, MinimiseProgram,

Minimize, MudLists, New, NewWindow, NextCommand, NextPane, NoCommandEcho,

North, NotesWorkArea, Open, OpenWorldsInStartupList, PageDown, Pageup, Paste,

PasteFile, PasteToMush, PluginWizard, Plugins, Preferences, PreviousCommand,

Print, PrintNotepad, PrintPreview, PrintSetup, QuickConnect, Quit,

QuoteForumCodes, QuoteLines, RecallText, ReconnectOnDisconnect,

RefreshRecalledData, Register, ReloadDefaults, ReloadNamesFile,

ReloadScriptFile, RemoveBlanks, RepeatLastCommand, RepeatLastWord,

ReplaceNotepad, ResetAllTimers, ResetToolbars, Restore, Save, SaveAs, SaveSelection,

SelectAll, SelectMatchingBrace, SendMailTo, SendToAllWorlds,

SendToCommandWindow, SendToScript, SendToWorld, South, SpellCheck, Start,

StopSoundPlaying, Take, TextAttributes, TileWindows, TileWindowsVertically,

TipOfTheDay, Trace, UnconvertHTMLspecial, Undo, UnixToDos, Up, UpperCase,

UsingHelp, ViewStatusbar, ViewToolbar, ViewWorldToolbar, WebPage, West,

Whisper, WindowsSocketInformation, WordCount, World1, World10, World2, World3,

World4, World5, World6, World7, World8, World9, WrapLines, WrapOutput

Return value

eNoSuchCommand: That command name was not recognised

eOK: Did the command (or attempted to do it)

Note that even if eOK (0) is returned, the command will not necessarily successfully execute. For example, DoCommand "WordCount" would not do anything if a "world" window was active, rather than a notepad window.

 View list of return code meanings

Lua example

DoCommand ("WindowsSocketInformation")

DoCommand ("FullScreenMode")

Jscript example

DoCommand ("WindowsSocketInformation");

DoCommand ("FullScreenMode");

PerlScript example

DoCommand ("WindowsSocketInformation");

DoCommand ("FullScreenMode");

Python example

world.DoCommand ("WindowsSocketInformation")

world.DoCommand ("FullScreenMode")

VBscript example

DoCommand "WindowsSocketInformation"

DoCommand "FullScreenMode"

See Also ...

Function

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

(Help topic: function=DoCommand)


EchoInput

Script function

world.EchoInput

 Read about scripting

Type

Property

Summary

A flag to indicate whether we are echoing command input to the output window

Prototype

boolean EchoInput;

 View list of data type meanings

Description

This property controls whether command input is echoed to the output window.

Return value

TRUE if echoing is enabled

FALSE if echoing is NOT enabled

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note (GetEchoInput ())

SetEchoInput  (true)

SetEchoInput  (false)

Lua notes

Lua implements this as two functions:

GetEchoInput - gets the echo input flag

SetEchoInput - sets the echo input flag

When setting the flag the flag is optional and defaults to true.

Jscript example

world.note(world.EchoInput);

world.EchoInput = true;

world.EchoInput = false;

PerlScript example

$world->note ($world->{EchoInput});

$world->{EchoInput} = false;

$world->{EchoInput} = true;

Python example

world.note(world.EchoInput)

world.EchoInput = True

world.EchoInput = False

VBscript example

world.note world.EchoInput

world.EchoInput = vbTrue

world.EchoInput = vbFalse;

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 LogInput (The property of whether commands are logged to the log file)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=EchoInput)


EditDistance

Script function

world.EditDistance

 Read about scripting

Type

Method

Summary

Returns the Levenshtein Edit Distance between two words

Prototype

long EditDistance(BSTR Source, BSTR Target);

 View list of data type meanings

Description

Returns the "edit distance" between two words.

This is intended for use in the spell checker or similar applications, where you need to know how close one word is to another.

The Levenshtein distance between two strings  is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character.

For example, the Levenshtein distance between "kitten" and "sitting" is 3, since the following three edits change one into the other, and there is no way to do it with fewer than three edits:

   1. kitten --> sitten (substitution of 's' for 'k')

   2. sitten --> sittin (substitution of 'i' for 'e')

   3. sittin --> sitting (insert 'g' at the end).

Return value

The edit distance between the two numbers.

Lua example

Note (EditDistance ("food", "fod"))      --> 1

Note (EditDistance ("food", "fodder"))   --> 3

Lua notes

Also available as utils.edit_distance.

VBscript example

Note EditDistance ("food", "fod")  ' --> 1

Note EditDistance ("food", "fodder")  ' --> 3

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=EditDistance)


EnableAlias

Script function

world.EnableAlias

 Read about scripting

Type

Method

Summary

Enables or disables an alias

Prototype

long EnableAlias(BSTR AliasName, BOOL Enabled);

 View list of data type meanings

Description

Enables or disables the named alias. An enabled alias is "active", otherwise it is ignored when processing commands you type.

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasNotFound: The named alias does not exist

eOK: completed OK

 View list of return code meanings

Lua example

EnableAlias ("teleport", true)

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableAlias("teleport", true);

PerlScript example

$world->EnableAlias("teleport", true);

Python example

world.EnableAlias("teleport", True)

VBscript example

world.EnableAlias "teleport", TRUE

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=EnableAlias)


EnableAliasGroup

Script function

world.EnableAliasGroup

 Read about scripting

Type

Method

Summary

Enables/disables a group of aliases

Prototype

long EnableAliasGroup(BSTR GroupName, BOOL Enabled);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of aliases do this:

  world.EnableAliasGroup "groupname", 1

To disable the entire group:

  world.EnableAliasGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount

  mycount = world.EnableAliasGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

Return value

A count of the number of items in that group.

Lua example

EnableAliasGroup ("groupname", true)  -- enable the group

EnableAliasGroup ("groupname", false)  -- disable the group

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableAliasGroup ("groupname", 1);  // enable the group

world.EnableAliasGroup ("groupname", 0);  // disable the group

PerlScript example

$world->EnableAliasGroup ("groupname", 1);  # enable the group

$world->EnableAliasGroup ("groupname", 0);  # disable the group

Python example

world.EnableAliasGroup ("groupname", 1)  # enable the group

world.EnableAliasGroup ("groupname", 0)  # disable the group

VBscript example

world.EnableAliasGroup "groupname", 1  ' enable the group

world.EnableAliasGroup "groupname", 0  ' disable the group

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=EnableAliasGroup)


EnableGroup

Script function

world.EnableGroup

 Read about scripting

Type

Method

Summary

Enables/disables a group of triggers, aliases and timers

Prototype

long EnableGroup(BSTR GroupName, BOOL Enabled);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of triggers, aliases and timers do this:

  world.EnableGroup "groupname", 1

To disable the entire group:

  world.EnableGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount

  mycount = world.EnableGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

Return value

A count of the number of items in that group.

Lua example

EnableGroup ("groupname", true)  -- enable the group

EnableGroup ("groupname", false)  -- disable the group

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableGroup ("groupname", 1);  // enable the group

world.EnableGroup ("groupname", 0);  // disable the group

PerlScript example

$world->EnableGroup ("groupname", 1);  # enable the group

$world->EnableGroup ("groupname", 0);  # disable the group

Python example

world.EnableGroup ("groupname", 1)  # enable the group

world.EnableGroup ("groupname", 0)  # disable the group

VBscript example

world.EnableGroup "groupname", 1  ' enable the group

world.EnableGroup "groupname", 0  ' disable the group

See Also ...

Topics

 Aliases

 Groups

 Timers

 Triggers

Functions

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetAliasInfo (Gets details about an alias)

 GetTimerInfo (Gets details about a timer)

 GetTriggerInfo (Gets details about a named trigger)

(Help topic: function=EnableGroup)


EnableMapping

Script function

world.EnableMapping

 Read about scripting

Type

Method

Summary

Enables or disables the auto-mapper

Prototype

void EnableMapping(boolean Enabled);

 View list of data type meanings

Description

Use this to enable or disable the inbuilt auto-mapper.

Return value

Nothing.

Lua example

EnableMapping (true)

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

EnableMapping (true);

PerlScript example

EnableMapping (1);

VBscript example

EnableMapping vbTrue

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=EnableMapping)


EnablePlugin

Script function

world.EnablePlugin

 Read about scripting

Type

Method

Summary

Enables or disables the specified plugin

Prototype

long EnablePlugin(BSTR PluginID, BOOL Enabled);

 View list of data type meanings

Description

Enables or disables the named plugin. An enabled plugin is "active", otherwise its triggers, timers and aliases are ignored.

You can use GetPluginInfo to see if the plugin is currently enabled.

If the plugin's "enabled" state changes (ie. from enabled to disabled, or disabled to enabled) then the appropriate routine in the plugin is called, if found ...

OnPluginEnable or OnPluginDisable

For example, you might have these routines in your plugin ...

sub OnPluginEnable

  world.Note world.GetPluginName & " has just been enabled."

end sub

sub OnPluginDisable

  world.Note world.GetPluginName & " has just been disabled."

end sub

Return value

eNoSuchPlugin: That plugin ID is not installed

eOK: enabled/disabled OK

 View list of return code meanings

Lua example

EnablePlugin ("982581e59ab42844527eec80", true)

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnablePlugin ("982581e59ab42844527eec80", true);

PerlScript example

$world->EnablePlugin ("982581e59ab42844527eec80", 1);

Python example

world.EnablePlugin ("982581e59ab42844527eec80", True)

VBscript example

world.EnablePlugin "982581e59ab42844527eec80", vbTrue

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=EnablePlugin)


EnableTimer

Script function

world.EnableTimer

 Read about scripting

Type

Method

Summary

Enables or disables an timer

Prototype

long EnableTimer(BSTR TimerName, BOOL Enabled);

 View list of data type meanings

Description

Enables or disables the named timer.  An enabled timer is "active", otherwise it is ignored when processing periodic events.

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerNotFound: The named timer does not exist

eOK: completed OK

 View list of return code meanings

Lua example

EnableTimer("heartbeat", true)

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableTimer("heartbeat", true);

PerlScript example

$world->EnableTimer("heartbeat", true);

Python example

world.EnableTimer("heartbeat", True)

VBscript example

world.EnableTimer "heartbeat", TRUE

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=EnableTimer)


EnableTimerGroup

Script function

world.EnableTimerGroup

 Read about scripting

Type

Method

Summary

Enables/disables a group of timers

Prototype

long EnableTimerGroup(BSTR GroupName, BOOL Enabled);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of timers do this:

  world.EnableTimerGroup "groupname", 1

To disable the entire group:

  world.EnableTimerGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount

  mycount = world.EnableTimerGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

Return value

A count of the number of items in that group.

Lua example

EnableTimerGroup ("groupname", true)  -- enable the group

EnableTimerGroup ("groupname", false)  -- disable the group

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableTimerGroup ("groupname", 1);  // enable the group

world.EnableTimerGroup ("groupname", 0);  // disable the group

PerlScript example

$world->EnableTimerGroup ("groupname", 1);  # enable the group

$world->EnableTimerGroup ("groupname", 0);  # disable the group

Python example

world.EnableTimerGroup ("groupname", 1)  # enable the group

world.EnableTimerGroup ("groupname", 0)  # disable the group

VBscript example

world.EnableTimerGroup "groupname", 1  ' enable the group

world.EnableTimerGroup "groupname", 0  ' disable the group

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimer (Enables or disables an timer)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=EnableTimerGroup)


EnableTrigger

Script function

world.EnableTrigger

 Read about scripting

Type

Method

Summary

Enables or disables a trigger

Prototype

long EnableTrigger(BSTR TriggerName, BOOL Enabled);

 View list of data type meanings

Description

Enables or disables the named trigger.  An enabled trigger is "active", otherwise it is ignored when processing incoming text from the MUD.

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerNotFound: The named trigger does not exist

eOK: completed OK

 View list of return code meanings

Lua example

EnableTrigger("monster", true)  -- enable trigger

EnableTrigger("monster", false)  -- disable trigger

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableTrigger("monster", true);  # enable trigger

world.EnableTrigger("monster", false);  # disable trigger

Python example

world.EnableTrigger("monster", True)  # enable trigger

world.EnableTrigger("monster", False)  # disable trigger

VBscript example

world.EnableTrigger "monster", TRUE  ' enable trigger

world.EnableTrigger "monster", FALSE  ' disable trigger

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=EnableTrigger)


EnableTriggerGroup

Script function

world.EnableTriggerGroup

 Read about scripting

Type

Method

Summary

Enables/disables a group of triggers

Prototype

long EnableTriggerGroup(BSTR GroupName, BOOL Enabled);

 View list of data type meanings

Description

Triggers, aliases and timers can be placed in "groups" where a group is a bunch of related items. Groups have names, there is no restriction on the name of a group. Ungrouped items have blank (empty) names.

To enable an entire group of triggers do this:

  world.EnableTriggerGroup "groupname", 1

To disable the entire group:

  world.EnableTriggerGroup "groupname", 0

For debugging purposes the function returns a count of the number of members in the group (not the number enabled, as some may already be enabled). eg.

  dim mycount

  mycount = world.EnableTriggerGroup ("groupname", 1)

If you are using plugins only the members of the current plugin (if any) are affected. If the call is made outside a plugin only the members of the group that are not in a plugin are affected.

Return value

A count of the number of items in that group.

Lua example

EnableTriggerGroup ("groupname", true)  -- enable the group

EnableTriggerGroup ("groupname", false)  -- disable the group

Lua notes

The enabled flag is optional, and defaults to true.

Jscript example

world.EnableTriggerGroup ("groupname", 1);  // enable the group

world.EnableTriggerGroup ("groupname", 0);  // disable the group

PerlScript example

$world->EnableTriggerGroup ("groupname", 1);  # enable the group

$world->EnableTriggerGroup ("groupname", 0);  # disable the group

Python example

world.EnableTriggerGroup ("groupname", 1)  # enable the group

world.EnableTriggerGroup ("groupname", 0)  # disable the group

VBscript example

world.EnableTriggerGroup "groupname", 1  ' enable the group

world.EnableTriggerGroup "groupname", 0  ' disable the group

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteGroup (Deletes a group of triggers, aliases and timers)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableAliasGroup (Enables/disables a group of aliases)

 EnableGroup (Enables/disables a group of triggers, aliases and timers)

 EnableTimerGroup (Enables/disables a group of timers)

 EnableTrigger (Enables or disables a trigger)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=EnableTriggerGroup)


ErrorDesc

Script function

world.ErrorDesc

 Read about scripting

Type

Method

Summary

Converts a MUSHclient script error code into an human-readable description

Prototype

BSTR ErrorDesc(long Code);

 View list of data type meanings

Description

This function converts a return code (such as 30008) into a human-readable form ("The name of this object is invalid").

The purpose is to allow scripts which fail to detect the reason and display it in human-readable form.

eg. (in VBscript)

result = SetVariable ("***", "abc")

if result <> 0 then

  Note ErrorDesc (result)

end if

Return value

A string containing the code converted to human-readable form, or the supplied argument converted to a string if the code is not in MUSHclient's internal list of error codes. At present, the range of codes that will be converted is 0, and 30001 to 30062.

Lua example

result = SetVariable ("***", "abc");

if result ~= 0 then

  Note (ErrorDesc (result))

end -- if

Lua notes

In Lua, it is simpler to use the error_desc table, which is available in earlier versions of MUSHclient also.

eg.

result = SetVariable ("***", "abc");

if result ~= 0 then

  Note (error_desc [result])

end -- if

This is simply a table-lookup in Lua, rather than a call to a MUSHclient function.

Jscript example

result = SetVariable ("***", "abc");

if (result != 0)

  {

  Note (ErrorDesc (result))

  }

VBscript example

result = SetVariable ("***", "abc")

if result <> 0 then

  Note ErrorDesc (result)

end if

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 ExportXML (Exports a world item in XML format)

 FilterPixel (Performs a filtering operation on one pixel)

 FixupEscapeSequences (Converts "escape sequences" like &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=ErrorDesc)


EvaluateSpeedwalk

Script function

world.EvaluateSpeedwalk

 Read about scripting

Type

Method

Summary

Evaluates a speed walk string

Prototype

BSTR EvaluateSpeedwalk(BSTR SpeedWalkString)

 View list of data type meanings

Description

Converts a supplied string based on the rules for "speed walking".

For example:

#4n3esuwdLW

This would move you: 4 times North, 3 times East, South, Up, West, Down and then "lock west"

Actions

Actions recognised are: C:close; O:open; L:lock; K:unlock (or nothing for no special action, just walk in that direction)

Directions

The directions recognised are: N:north, S:south, E:east, W:west, U:up, D:down.

Filler

You can also enter "F" for a speed walk "filler". This is for MUDs that reject multiple identical commands. For example, if you need to walk West 30 times, but your MUD disconnects you after 20 identical commands, enter:

#15w f 15w

The exact text that is sent by the "filler" is customisable from the "Input" world configuration screen. A suggested filler command would be something harmless, like LOOK.

Multipliers

You may also enter a one or two-digit multiplier in the range 1 to 99. The multiplier affects the *next* direction entered, e.g. "5s" means go South 5 times.

Spaces are accepted in the speed walk string, and ignored.

Non-standard directions

You can supply non-standard directions (eg. NE for NorthEast) by putting them in brackets.

For example:

5N 4W (ne) (say open sesame) 5U 4(se)

You can also supply the "reverse" direction after a "/" character, in case you want to reverse the speedwalk direction later.

For example:

5N 4W (ne/sw) (say open sesame/kick door) 5U 4(se/nw)

When speedwalking, only the characters before the slash are evaluated.

Return value

The supplied string, converted from speed walk characters to directions, with a "newline" between each direction.

If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.

Lua example

Note(EvaluateSpeedwalk ("4n3esuwdLW"))

Jscript example

world.note(world.EvaluateSpeedwalk ("4n3esuwdLW"));

PerlScript example

$world->note($world->EvaluateSpeedwalk ("4n3esuwdLW"));

Python example

world.note(world.EvaluateSpeedwalk ("4n3esuwdLW"))

VBscript example

world.note world.EvaluateSpeedwalk ("4n3esuwdLW")

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

 Speed walking

Functions

 Queue (Queues a command for sending at the "speed walk" rate.)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 ReverseSpeedwalk (Reverses a speed walk string)

 Send (Sends a message to the MUD)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=EvaluateSpeedwalk)


Execute

Script function

world.Execute

 Read about scripting

Type

Method

Summary

Executes a command as if you had typed it into the command window

Prototype

long Execute(BSTR Command);

 View list of data type meanings

Description

The Execute function lets you execute arbitrary commands as if they were typed into the command window.

The command will be parsed exactly the same as the command window parser, depending on currently-set options (eg. speedwalking, command stacking, scripting etc.).

The only difference is that the command will:

* Not be placed in the command history (as you didn't actually type it in)

* Not unpause the output window if it is paused

There is a possibility that you might accidentally nest calls to execute, for example if an alias called itself, so MUSHclient limits nested calls to the Execute function to 20 levels of nesting.

Note that the Execute function ignores the auto-say setting. Thus you can still use Execute to do things, even if the player has turned on auto-say for a quick chat. However if you are planning to do script commands you will need to be sure that the scripting prefix has not changed.

If you are planning to execute a script using Execute you should probably find the current script prefix (using world.GetOption) rather than relying it on being the same all the time.

Return value

eOK: Executed OK

eWorldClosed: World is closed

eCommandsNestedTooDeeply: Commands nested too deeply

 View list of return code meanings

Lua example

Execute ("north")  -- normal command

Execute ("4s 3e")  -- speed walk

Execute ("/Debug ('colours') ")  -- execute a script

Jscript example

world.Execute ("north");  // normal command

world.Execute ("4s 3e");  // speed walk

world.Execute ("/world.Debug ("colours ") ");  // execute a script

PerlScript example

$world->Execute ("north");  # normal command

$world->Execute ("4s 3e");  # speed walk

Python example

world.Execute ("north")  # normal command

world.Execute ("4s 3e")  # speed walk

world.Execute ("world.Debug ("colours ") ")  # execute a script

VBscript example

world.Execute "north"  ' normal command

world.Execute "#4s 3e"  ' speed walk

world.Execute "/world.Debug ""colours "" "  ' execute a script

See Also ...

Function

 Send (Sends a message to the MUD)

(Help topic: function=Execute)


ExportXML

Script function

world.ExportXML

 Read about scripting

Type

Method

Summary

Exports a world item in XML format

Prototype

BSTR ExportXML(short Type, BSTR Name);

 View list of data type meanings

Description

This lets you export one trigger, timer, alias, macro, keypad item or variable in XML format. This is symmetrical with the ImportXML function - a trigger exported with ExportXML will be syntactically correct for importing with ImportXML. However, it may not actually import if, say, there is a clash where two triggers both have the same label.

This would let you send triggers etc. from one world to another in an automated way, or from one client to another if you built some chat scripting around these functions.

The various types of things are numbered:

0 = trigger

1 = alias

2 = timer

3 = macro

4 = variable

5 = keypad

Return value

The XML text of the nominated item. If the "type" is not valid, or the item cannot be found, then the return value is the empty string.

Lua example

Note (ExportXML (0, "mytrigger"))

Jscript example

world.Note (world.ExportXML (0, "mytrigger"));

PerlScript example

Note (ExportXML (0, "mytrigger"));

Python example

world.Note (world.ExportXML (0, "mytrigger"));

VBscript example

world.Note world.ExportXML (0, "mytrigger")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 FilterPixel (Performs a filtering operation on one pixel)

 FixupEscapeSequences (Converts "escape sequences" like &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=ExportXML)


FilterPixel

Script function

world.FilterPixel

 Read about scripting

Type

Method

Summary

Performs a filtering operation on one pixel

Prototype

long FilterPixel(long Pixel, short Operation, double Options);

 View list of data type meanings

Description

This applies the specified filtering operation to the pixel supplied (an RGB code).

This does largely the same thing as WindowFilter, except it operates on a single pixel (that is, a single RGB colour). This does the same operations (with the same codes as for WindowFilter) excepting the ones which require more than one pixel (like Blur, Sharpen, Find Edges, and Emboss).

Operation - the filter operation. At present, one of:

1 - Apply colour noise

2 - Apply monochrome noise

7 - Adjust Brightness (by adding Options to the pixel)

8 - Adjust Contrast

9 - Adjust Gamma

10 - Adjust Brightness for red channel only  (by adding Options to the pixel)

11 - Adjust Contrast for red channel only

12 - Adjust Gamma for red channel only

13 - Adjust Brightness for green channel only  (by adding Options to the pixel)

14 - Adjust Contrast for green channel only

15 - Adjust Gamma for green channel only

16 - Adjust Brightness for blue channel only  (by adding Options to the pixel)

17 - Adjust Contrast for blue channel only

18 - Adjust Gamma for blue channel only

19 - Convert to grayscale - mix red/green/blue equally

20 - Convert to grayscale - mix 30% red + 59% green + 11% blue for normal perception

21 - Adjust Brightness (by multiplying Options by the pixel)

22 - Adjust Brightness for red channel only  (by multiplying Options by the pixel)

23 - Adjust Brightness for green channel only   (by multiplying Options by the pixel)

24 - Adjust Brightness for blue channel only   (by multiplying Options by the pixel)

27 - Average - the pixel's average colour (that is, itself)

Single channel operations - the modes which specify a single channel (10 to 18, 22 to 24) operate on that colour channel only (red, green or blue) leaving the others untouched. Thus by, say, increasing brightness on the red channel you add to the red value, but leave green and blue alone, making the image look redder. However decreasing brightness on the red channel would make the image look more cyan (as cyan is the complementary colour to red).

The complementary colours are:

red / cyan

green / magenta

blue / yellow

Options - filtering options.

For the Noise filter:

A number from about 0 to 255 indicating how much noise to add.

For the Brightness (additive) filter:

A number from -255 to +255 to indicate the amount to increase (or decrease) the value of the pixel - by adding. A negative number will make it darker, a positive number will make it brighter.

For the Brightness (multiplicative) filter:

A number which is multiplied by the value of the pixel. A number less than 1 will make it darker, a number greater than 1 will make it brighter. However black (zero) will remain black.

For the Contrast filter:

A number to indicate the amount to multiply by the value of the pixel. Zero will make the picture zero contrast, that is totally grey. If you use 1 the pixel will be normal contrast (as each pixel is multiplied by 1). A value between 0 and 1 will be lower contrast. A value above 1 will increase contrast. Negative numbers will have the effect of making the image look negative.

For the Gamma filter:

A number to indicate the amount of Gamma adjustment. Mathematically the pixel is raised to the power of this number. Thus, a gamma of 1 will result in no change. A gamma of 2 will darken the image somewhat. A gamma of 0.5 will lighten the image. A gamma of zero will make the image totally white.

The difference between gamma and brightness is that increasing brightness simply adds to the value of each pixel, so that black becomes gray, and bright pixel become clipped. Similarly, decreasing brightness means that white pixels become grey, and dark ones are clipped.

However because gamma is a power function, black stays black, and white stays white, with the biggest change in the mid range. A higher gamma value results in a darker image with more contrast. A lower gamma value (between 0 and 1) results in a lighter image with less contrast.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

-1 : filter mode not in the list above.

Otherwise, the filtered pixel as an RGB code

Lua example

-- Brightness

FilterPixel (0x445566, 7, -4) -- lower by 4 (gives 0x405162)

FilterPixel (0x445566, 7, 10) -- raise by 10 (gives 0x4e5f70)

FilterPixel (0x445566, 21, 0.5) -- halve the brightness (gives 0x222a33)

FilterPixel (0x445566, 21, 2) -- double the brightness (gives 0x88aacc)

-- Contrast

FilterPixel (0x445566, 8, 0.5) -- reduce (gives 0x626a73)

FilterPixel (0x445566, 8, 2) -- increase (gives 0x082a4c)

-- Gamma

FilterPixel (0x445566, 9, 0.3) -- brighter, lower contrast (gives 0xabb7c1)

FilterPixel (0x445566, 9, 1.5) -- darker, higher contrast (gives 0x233140)

FilterPixel (0x445566, 9, 5)   -- very dark and contrasty (gives 0x000102)

Lua notes

You can use the following constants for the Operation argument:

miniwin.filter_noise = 1

miniwin.filter_monochrome_noise = 2

miniwin.filter_brightness = 7

miniwin.filter_contrast = 8

miniwin.filter_gamma = 9

miniwin.filter_red_brightness = 10

miniwin.filter_red_contrast = 11

miniwin.filter_red_gamma = 12

miniwin.filter_green_brightness = 13

miniwin.filter_green_contrast = 14

miniwin.filter_green_gamma = 15

miniwin.filter_blue_brightness = 16

miniwin.filter_blue_contrast = 17

miniwin.filter_blue_gamma = 18

miniwin.filter_grayscale = 19

miniwin.filter_normal_grayscale = 20

miniwin.filter_brightness_multiply = 21

miniwin.filter_red_brightness_multiply = 22

miniwin.filter_green_brightness_multiply = 23

miniwin.filter_blue_brightness_multiply = 24

miniwin.filter_average = 27

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 FixupEscapeSequences (Converts "escape sequences" like &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

(Help topic: function=FilterPixel)


FixupEscapeSequences

Script function

world.FixupEscapeSequences

 Read about scripting

Type

Method

Summary

Converts "escape sequences" like &#x5C;t to their equivalent codes.

Prototype

BSTR FixupEscapeSequences(BSTR Source);

 View list of data type meanings

Description

This provides a script interface to the internal routine used by MUSHclient to convert special "escape" sequences into the ASCII equivalents.

The following sequences are recognised:

 \a Bell (alert)

 \b Backspace

 \f Formfeed

 \n New line

 \r Carriage return

 \t Horizontal tab

 \v Vertical tab

 \' Single quotation mark

 \" Double quotation mark

 \\ Backslash

 \? Literal question mark

 \xhh ASCII character in hexadecimal notation

Return value

The source string with any escape sequences (as described above) replaced by the equivalent code.

Lua example

Send(FixupEscapeSequences(mystring))

-- In Lua a quoted sequence like "\n" will already

-- be interpreted by the Lua interpreter

Jscript example

world.Send(world.FixupEscapeSequences(mystring));

// In JScript a quoted sequence like "\n" will already

// be interpreted by the JScript interpreter

PerlScript example

$world->Send($world->FixupEscapeSequences($mystring));

// In PerlScript a quoted sequence like "\n" will already

// be interpreted by the PerlScript interpreter

Python example

world.Send(world.FixupEscapeSequences(mystring))

VBscript example

world.send world.FixupEscapeSequences ("go north \n go west")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=FixupEscapeSequences)


FixupHTML

Script function

world.FixupHTML

 Read about scripting

Type

Method

Summary

Fixes up text for writing as HTML

Prototype

BSTR FixupHTML(BSTR StringToConvert);

 View list of data type meanings

Description

This translates text so that it can be logged as HTML.

It will translate "<", ">" and "&" to the HTML equivalents (eg. &lt; ), otherwise a line like this: "go <north>" would not log correctly as HTML.

This is intended for use in scripts that are used to log to the log file, where you are writing out a log file in HTML.

Return value

The supplied string with the following characters replaced with the HTML "escaped" equivalents:

<   &lt;

>   &gt;

&   &amp;

"   &quot;

Lua example

Note(FixupHTML("I will go <north> here"))

Jscript example

world.note(world.FixupHTML("I will go <north> here"));

PerlScript example

$world->note($world->FixupHTML("I will go <north> here"));

Python example

world.note(world.FixupHTML("I will go <north> here"))

VBscript example

world.note world.FixupHTML ("I will go <north> here")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;t to their equivalent codes.)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=FixupHTML)


FlashIcon

Script function

world.FlashIcon

 Read about scripting

Type

Method

Summary

Flashes the MUSHclient icon on the Windows taskbar

Prototype

void FlashIcon();

 View list of data type meanings

Description

This function flashes the MUSHclient icon on the Windows taskbar in the same way that MUSHclient does if you have checked the option "New activity flashes taskbar".

Return value

None.

Lua example

FlashIcon ( )

VBscript example

FlashIcon

See Also ...

Topic

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;t to their equivalent codes.)

 FixupHTML (Fixes up text for writing as HTML)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=FlashIcon)


FlushLog

Script function

world.FlushLog

 Read about scripting

Type

Method

Summary

Flushes the log file to disk

Prototype

long FlushLog();

 View list of data type meanings

Description

This flushes (writes out) any cached data for the currently open log file.

Return value

eOK: closed OK

eLogFileNotOpen: log file was not open

 View list of return code meanings

Lua example

FlushLog()

Jscript example

world.FlushLog();

PerlScript example

$world->FlushLog;

Python example

world.FlushLog

VBscript example

world.FlushLog

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=FlushLog)


GenerateName

Script function

world.GenerateName

 Read about scripting

Type

Method

Summary

Generates a random character name

Prototype

VARIANT GenerateName();

 View list of data type meanings

Description

Generates a random character name based on the names in the names file previously loaded with ReadNamesFile.

Return value

If a names file has not been loaded, the return value is a NULL variant.

Otherwise, the return value is the generated name.

Lua example

-- generate 20 names

for i = 1, 20 do

  Note(GenerateName())

end

Jscript example

// generate 20 names

for (i = 0; i < 20; i++)

  world.note(world.generatename ());

PerlScript example

# generate 20 names

for ($i = 0; $i < 20; $i++)

  {

  $world->note($world->generatename ());

  }

Python example

# generate 20 names

for i in range (20):

  world.note(world.generatename )

VBscript example

' generate 20 names

for i = 1 to 20

  world.note world.generatename

next

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;t to their equivalent codes.)

 FixupHTML (Fixes up text for writing as HTML)

 FlashIcon (Flashes the MUSHclient icon on the Windows taskbar)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GenerateName)


GetAlias

Script function

world.GetAlias

 Read about scripting

Type

Method

Summary

Gets details about an alias

Prototype

long GetAlias(BSTR AliasName, VARIANT* MatchText, VARIANT* ResponseText, VARIANT* Parameter, VARIANT* Flags, VARIANT* ScriptName);

 View list of data type meanings

Description

Gets details about the specified alias name.

See AddAlias for a description of the meanings of the fields.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetAliasInfo instead. See below for how it works with Lua.

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasNotFound: The named alias does not exist

eOK: completed OK

 View list of return code meanings

Lua example

local iStatus

local almatch

local alresponse

local alflags

local alscriptname

iStatus, almatch, alresponse, alflags, alscriptname  =

   GetAlias ("myalias")

print (iStatus, almatch, alresponse, alflags, alscriptname)

Lua notes

Lua does not let you call by reference, however it can return multiple results.

Thus GetAlias is implemented to return the various fields as a multiple-return result, as shown in the example above.

The field Parameter is deprecated and thus not returned.

Jscript example

// Use GetAliasInfo when using Jscript

PerlScript example

# Use GetAliasInfo when using PerlScript

Python example

# Use GetAliasInfo when using Python

VBscript example

dim alname

dim almatch

dim alresponse

dim alparameter

dim alflags

dim alscriptname

dim iStatus

iStatus = world.getalias (alname, almatch, alresponse, _

              alparameter, alflags, alscriptname)

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetAlias)


GetAliasInfo

Script function

world.GetAliasInfo

 Read about scripting

Type

Method

Summary

Gets details about an alias

Prototype

VARIANT GetAliasInfo(BSTR AliasName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified alias name.

You can obtain one of 31 "types" of information about the alias by specifying an "InfoType". The possible InfoTypes are:

 1: What to match on (string)

 2: What to send (string)

 3: Script procedure name (string)

 4: Omit from log (boolean)

 5: Omit from output (boolean)

 6: Enabled (boolean)

 7: Regular expression  (boolean)

 8: Ignore case (boolean)

 9: Expand variables (boolean)

10: Invocation count (long)

11: Times matched (long)

12: Menu (boolean)

13: Date/time alias last matched (date)

14: 'temporary' flag (boolean)

15: Alias was included from an include file (boolean)

16: Group name (string)

17: Variable name to set (string)

18: Send-to location (long)

19: 'keep-evaluating' flag (boolean)

20: Sequence number (long)

21: 'echo alias' flag (boolean)

22: 'omit from command history' flag (boolean)

23: User option value (long)

24: Number of matches to regular expression (most recent match) (long)

25: The string we matched against (last alias text matched against) (string)

26: Executing-script flag (boolean)

27: Script is valid flag (boolean)

28: Error number from PCRE when evaluating last match (long), zero if none

29: 'one shot' flag (boolean)

30: Time taken (in seconds) to test aliases (including un-matched ones) (double)

31: Number of attempts to match this alias (long)

101: Wildcard %1 from last time it matched

102: Wildcard %2 from last time it matched

103: Wildcard %3 from last time it matched

104: Wildcard %4 from last time it matched

105: Wildcard %5 from last time it matched

106: Wildcard %6 from last time it matched

107: Wildcard %7 from last time it matched

108: Wildcard %8 from last time it matched

109: Wildcard %9 from last time it matched

110: Wildcard %0 from last time it matched

Other wildcards can be extracted by using GetAliasWildcard.

The word in brackets indicates the "type" of data returned.

  String: a character string (eg. "north")

  Boolean: TRUE or FALSE

  Long: a 32-bit number

The field "invocation count" is a count of how many times the script routine was called.

The field "times matched" is a count of how many times the alias matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

The meanings of the "send-to" field are:

 0: World

 1: Command window

 2: Output window

 3: Status line

 4: Notepad (new)

 5: Notepad (append)

 6: Log File

 7: Notepad (replace)

 8: Command queue

 9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See AddAlias for a description of the meanings of the fields.

Return value

The specified information about the alias, as described above.

An EMPTY variant, if the alias does not exist.

A NULL variant if the alias name is invalid.

A NULL variant if the InfoType is not a valid type.

Lua example

Note (GetAliasInfo("my_alias", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

/world.note(world.GetAliasInfo ("my_alias", 2));

PerlScript example

/$world->note ($world->GetAliasInfo ("my_alias", 2));

Python example

world.note(world.GetAliasInfo ("my_alias", 2))

VBscript example

world.note world.GetAliasInfo ("my_alias", 2)

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetInfo (Gets information about the current world)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetAliasInfo)


GetAliasList

Script function

world.GetAliasList

 Read about scripting

Type

Method

Summary

Gets the list of aliases

Prototype

VARIANT GetAliasList();

 View list of data type meanings

Description

Returns an array of all the named aliases currently defined. You can then use GetAlias or GetAliasInfo for more details about each one.

Note - from version 3.40 onwards GetAliasList returns all aliases, even unlabelled ones. The unlabelled aliases will have assigned an "internal" label (like "*alias42") that can be used in GetAliasInfo, and similar routines.

Return value

If there are no aliases (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the aliases. Use "ubound" to find the number of aliases in the list. You can then use "GetAlias" to find details about each alias.

Lua example

al = GetAliasList()

if al then

  for k, v in ipairs (al) do

    Note (v)

  end  -- for

end -- if we have any aliases

Lua notes

Lua returns nil where applicable instead of an "empty variant".

Jscript example

aliaslist = new VBArray(world.GetAliasList()).toArray();

if (aliaslist)  // if not empty

 for (i = 0; i < aliaslist.length; i++)

   world.note(aliaslist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetAliasList))

 {

 $world->note($item);

 }

Python example

aliaslist = world.GetAliasList

if (aliaslist ):

  for a in aliaslist : world.Note (a)

VBscript example

dim alList

alList = world.GetAliasList

If Not IsEmpty (alList) then

  For Each name In alList

    world.Note name

  Next

End If

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetAliasList)


GetAliasOption

Script function

world.GetAliasOption

 Read about scripting

Type

Method

Summary

Gets the value of a named alias option

Prototype

VARIANT GetAliasOption(BSTR AliasName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of an alias option.

You must specify the name of an existing alias, and an alias option from the list below. These are the same names as used in the XML world files for alias options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing aliases copied to the clipboard or in world files and plugins. You already know the name when getting the alias option (it is AliasName), and this function is provided to modify existing aliases, not rename them. To change the name of an alias use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddAlias.

If GetAliasOption is called from within a plugin, the aliases for the current plugin are used, not the "global" MUSHclient aliases.

To find options for other plugins use GetPluginAliasOption.

The various option names are:

"echo_alias":               y/n - echo alias itself to output window

"enabled":                  y/n - alias is enabled

"expand_variables":         y/n - expand variables (like @target)

"group":                    (string - group name)

"ignore_case":              y/n - caseless matching

"keep_evaluating":          y/n - evaluate next alias in sequence

"match":                    (string - what to match)

"menu":                     y/n - add alias to menu that appears if you LH click

"name":                     (string - name/label of alias)

"omit_from_command_history":   y/n - omit alias from the command history

"omit_from_log":            y/n - omit alias from log file

"omit_from_output":         y/n - omit sent text from the output window

"one_shot":                 y/n - alias is deleted after firing

"regexp":                   y/n - regular expression

"script":                   (string - name of function to call)

"send":                     (multi-line string - what to send)

"send_to":                  0 - 13 - "send to" location (see below)

"sequence":                 0 - 10000 - sequence number in which to check - lower first

"user":                     -2147483647 to 2147483647 - user-defined number

"variable":                 (string - name of variable to send to)

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Return value

As described above.

Lua example

Note (GetAliasOption ("myalias", "match"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

Note (GetAliasOption ("myalias", "match"));

PerlScript example

$world->Note ($world->GetAliasOption ("myalias", "match"));

Python example

world.Note (world.GetAliasOption ("myalias", "match"))

VBscript example

Note GetAliasOption ("myalias", "match")

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetAliasOption)


GetAliasWildcard

Script function

world.GetAliasWildcard

 Read about scripting

Type

Method

Summary

Returns the contents of the specified wildcard for the named alias

Prototype

VARIANT GetAliasWildcard(BSTR AliasName, BSTR WildcardName);

 View list of data type meanings

Description

Once a alias has matched you can extract any of the wildcards for that alias using this function.

The wildcards can be specified by name or number (if by number pass a string which is the appropriate number).

You can set up a named wildcard like this:

Match: Tell (?P<who>.*?) (?P<what>.*)

In this case we have 2 wildcards, named "who" and "what".

Now we can extract wildcards like this:

x = GetAliasWildcard ("myalias", "who")  ' get wildcard named 'who'

x = GetAliasWildcard ("myalias", "what") ' get wildcard named 'what'

x = GetAliasWildcard ("myalias", "22")   ' get wildcard 22 (if it exists)

You can have up to 999 wildcards, plus wildcard 0 which represents the entire matching string.

You can use GetAliasInfo selector 24 to find how many wildcards matched.

Each wildcard will have a number and may optionally have a name.

Return value

The contents of the specified alias wildcard, as described above.

An EMPTY variant, if the alias does not exist.

A NULL variant if the alias name is invalid.

An empty string if the wildcard does not exist. An empty string is the string "", this is different from an EMPTY variant.

Lua example

local x

x = GetAliasWildcard ("myalias", "who")  -- get wildcard named 'who'

x = GetAliasWildcard ("myalias", "what") -- get wildcard named 'what'

x = GetAliasWildcard ("myalias", "22")   -- get wildcard 22 (if it exists)

Lua notes

Inside an alias script function you can access named wildcards by simply putting the name after the wildcards argument. eg.

function myAliasFunction (name, line, wildcards)

  Note (wildcards.who)  --> access named wildcards "who"

end

VBscript example

dim x

x = GetAliasWildcard ("myalias", "who")  ' get wildcard named 'who'

x = GetAliasWildcard ("myalias", "what") ' get wildcard named 'what'

x = GetAliasWildcard ("myalias", "22")   ' get wildcard 22 (if it exists)

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetAliasWildcard)


GetAlphaOption

Script function

world.GetAlphaOption

 Read about scripting

Type

Method

Summary

Gets the value of an alphanumeric configuration option

Prototype

VARIANT GetAlphaOption(BSTR OptionName);

 View list of data type meanings

Description

Gets the value of an alphanumeric world option (text option), such as player name, MUD name etc.

You can use GetAlphaOptionList to get a list of the names of all possible options.

Return value

The value of the requested option, or an "empty" variant if the option does not exist.

Lua example

Note (GetAlphaOption("player"))

Jscript example

/world.note(world.getalphaoption ("player"));

PerlScript example

/$world->note ($world->getalphaoption ("player"));

Python example

world.note(world.getalphaoption ("player"))

VBscript example

world.note world.getalphaoption ("player")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetInfo (Gets information about the current world)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetAlphaOption)


GetAlphaOptionList

Script function

world.GetAlphaOptionList

 Read about scripting

Type

Method

Summary

Gets the list of world alphanumeric options

Prototype

VARIANT GetAlphaOptionList();

 View list of data type meanings

Description

Returns a variant array which is a list of all options that you can get with GetAlphaOption or set with SetAlphaOption.

The examples show extracting all option names, and their values.

The option names should be reasonably self-explanatory.

Return value

It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetAlphaOption" to return the value for that particular option, or "SetAlphaOption" to set that option value.

Lua example

for k, v in pairs (GetAlphaOptionList ()) do

  Note (v)

end

Jscript example

optionlist = new VBArray(world.GetAlphaOptionList()).toArray();

for (i = 0; i < optionlist .length; i++)

  world.note(optionlist [i] + " = " + world.GetAlphaOption (optionlist [i] ));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetAlphaOptionList))

  {

  $world->note($item . " = " . $world->GetAlphaOption($item));

  }

Python example

for opt in world.GetAlphaOptionList: world.Note (opt)

VBscript example

For Each opt In world.GetAlphaOptionList

   world.note opt + " = " + cstr (world.GetAlphaOption ( opt ))

Next

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetInfo (Gets information about the current world)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetAlphaOptionList)


GetChatInfo

Script function

world.GetChatInfo

 Read about scripting

Type

Method

Summary

Get information about a chat connection

Prototype

VARIANT GetChatInfo(long ChatID, short InfoType);

 View list of data type meanings

Description

Gets details about the specified chat session.

You can obtain one of 41 "types" of information about the chat session by specifying an "InfoType". The possible InfoTypes are:

  1: Server name

  2: User (ie. their chat name)

  3: Group name

  4: Client version

  5: Call IP (address to call to get them)

  6: Address (address they actually are)

  7: Port    (incoming port)

  8: Call port (port to call them on)

  9: Status

 10: Type   (0 = MudMaster protocol)

 11: ID     (internal chat ID)

 12: Incoming (true = they called us, false = we called them)

 13: Can snoop flag

 14: Snooping flag

 15: They are snooping us flag

 16: Send commands flag

 17: Private flag

 18: Can send files flag

 19: Ignore them flag

 20: Recent ping time

 21: Started at time

 22: Last message in time

 23: Last message out time

 24: Started file transfer time

 25: We are transferring a file flag

 26: File transfer is a send (false = receive)

 27: File name being transferred

 28: Full file path (on our disk)

 29: File size bytes

 30: File blocks

 31: Blocks already transferred

 32: Block size

 33: Incoming personal count

 34: Incoming all count

 35: Incoming group count

 36: Outgoing personal count

 37: Outgoing all count

 38: Outgoing group count

 39: Messages count

 40: File xfer bytes in count

 41: File xfer bytes out count

 42: zChat stamp ID

 43: Email address (from zChat)

 44: PGP key (from zChat) - not used by MUSHclient

 45: Status number (from zChat)

 46: User option value (long)

Return value

The specified information about the chat session, as described above.

A NULL variant if the chat session does not exist.

An EMPTY variant if the InfoType is not a valid type.

Lua example

Note ("Version: " .. GetChatInfo (id, 4))

Jscript example

Note ("Version: " + GetChatInfo (id, 4));

PerlScript example

Note ("Version: " . GetChatInfo (id, 4));

Python example

world.Note ("Version: " + str (world.GetChatInfo (id, 4)))

VBscript example

Note "Version: " & GetChatInfo (id, 4)

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=GetChatInfo)


GetChatList

Script function

world.GetChatList

 Read about scripting

Type

Method

Summary

Gets the list of chat sessions

Prototype

VARIANT GetChatList();

 View list of data type meanings

Description

Returns an array of all the chat sessions which are currently connected. You can then use various "chat" routines to do something with that list.

Return value

If there are no chat sessions then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the IDs of all the chat sessions. Use "ubound" to find the number of chat sessions in the list. You can then use "GetChatInfo" to find details about each session. See the example for how to do this. You can paste this example into an "Immediate" window (CTRL+I) to test it.

Lua example

for k, v in pairs (GetChatList ()) do

  Note (v)

end

Jscript example

chatList = new VBArray(GetChatList()).toArray();

if (chatList)  // if not empty

 for (i = 0; i < chatList.length; i++)

   world.note(chatList [i] + " = " + GetChatInfo (chatList [i], 2));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetChatList))

 {

 Note($item . " = " . GetChatInfo ($item, 2));

 }

Python example

chatList = world.GetChatList

if (chatList ):

  for c in chatList : world.Note (str (c) + " = " +

              world.GetChatInfo (c, 2))

VBscript example

dim chatList

chatList = GetChatList

If Not IsEmpty (chatList) then

  For Each c In chatList

    Note c & " = " & GetChatInfo (c, 2)

  Next

End If

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=GetChatList)


GetChatOption

Script function

world.GetChatOption

 Read about scripting

Type

Method

Summary

Gets the value of a chat session option

Prototype

VARIANT GetChatOption(long ID, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a chat session option.

You must specify the identifier of a current chat session, and a chat option from the list below.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the chat session does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

OPTION NAMES

"address" - TCP/IP address of remote user (address to call them)

"can_send_commands" - can that user send us commands?

"can_send_files" - can that user send us files?

"can_snoop" - can that user snoop on our session?

"group" - their group name

"ignore" - ignore them?

"private" - private session?

"served" - incoming call?

"server" - TCP/IP address of remote user

"user" - user value (for scripting, is not used by MUSHclient)

"username" - their chat name

"version" - what version client they are using

Return value

As described above.

Lua example

Note (GetChatOption (ChatGetID ("nick"), "group"))

Jscript example

Note (GetChatOption (ChatGetID ("nick"), "group"));

PerlScript example

Note (GetChatOption (ChatGetID ("nick"), "group"));

Python example

world.Note (world.GetChatOption (world.ChatGetID ("nick"), "group"))

VBscript example

Note GetChatOption (ChatGetID ("nick"), "group")

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

 SetChatOption (Sets the value of a chat session option)

(Help topic: function=GetChatOption)


GetClipboard

Script function

world.GetClipboard

 Read about scripting

Type

Method

Summary

Gets the clipboard contents

Prototype

BSTR GetClipboard();

 View list of data type meanings

Description

Returns the clipboard contents, if the clipboard contains straight text. If there is no text on the clipboard, it returns the empty string.

Return value

The clipboard contents, of an empty string if the clipboard does not contain text.

Lua example

Note (GetClipboard ())

Jscript example

Note (GetClipboard ());

PerlScript example

Note (GetClipboard ());

Python example

world.Note (world.GetClipboard)

VBscript example

Note GetClipboard

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GetClipboard)


GetCommand

Script function

world.GetCommand

 Read about scripting

Type

Method

Summary

Gets the current command in the command window

Prototype

BSTR GetCommand();

 View list of data type meanings

Description

Returns the current contents of the command window, without changing it.

If more than one window is open for this world, it uses the first window in the window list.

Return value

The contents of the command window.

Lua example

Note (GetCommand ())

Jscript example

world.Note (world.GetCommand ());

PerlScript example

$world->Note ($world->GetCommand ());

Python example

world.Note (world.GetCommand )

VBscript example

world.Note world.GetCommand

See Also ...

Functions

 GetCommandList (Returns some or all commands from the command history)

 PushCommand (Pushes the current command into the command history list)

 SelectCommand (Selects (highlights) the current command in the command window)

 SetCommand (Sends text to the command window)

(Help topic: function=GetCommand)


GetCommandList

Script function

world.GetCommandList

 Read about scripting

Type

Method

Summary

Returns some or all commands from the command history

Prototype

VARIANT GetCommandList(long Count);

 View list of data type meanings

Description

This returns a variant array of the nominated number of most recent commands (in the command history window).

You can get all available commands by requesting a count of zero. (You can get the most recently saved command by requesting a count of 1).

If you request more than the available number, then the number of items in the array may be less than that requested.

You can get the current command (not yet in the command history list) by using world.GetCommand.

Return value

If there are no commands in the history list then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the specified number of commands (counting from the most recent). Use "ubound" to find the number of commands in the list.

Lua example

--

-- Get last 10 commands

--

for k, v in ipairs (GetCommandList (10)) do

  print (k, v)   --> command number, what the command was

end

Jscript example

//

// Get last 10 commands

//

  commandList = new VBArray(world.GetCommandList (10)).toArray();

  if (commandList)

    for (i = 0; i < commandList.length; i++)

        world.note (commandList [i]);

PerlScript example

#

#  Get last 10 commands

#

foreach $item (Win32::OLE::in ($world->GetCommandList (10)))

 {

 $world->note($item);

 }

Python example

#

# Get last 10 commands

#

commandList = world.GetCommandList (10)

if (commandList ):

  for c in commandList : world.Note (c)

VBscript example

dim commandList

dim iCount

'

' Get last 10 commands

'

  commandList = world.GetCommandList (10)

  If Not IsEmpty (commandList) Then

    For Each command In commandList

      world.Note command

    Next

  End If

'

' ------------------------

'

'

' Get most recent command

'

  world.note world.getcommandlist (1) (0)

See Also ...

Functions

 GetCommand (Gets the current command in the command window)

 PushCommand (Pushes the current command into the command history list)

 SelectCommand (Selects (highlights) the current command in the command window)

 SetCommand (Sends text to the command window)

(Help topic: function=GetCommandList)


GetConnectDuration

Script function

world.GetConnectDuration

 Read about scripting

Type

Method

Summary

Returns the number of seconds this world has been connected.

Prototype

long GetConnectDuration();

 View list of data type meanings

Description

Returns the number of seconds the world has been connected, or zero if the world is not currently connected.

Return value

The number of seconds this world has been connected.

Lua example

Note(GetConnectDuration())

Jscript example

world.note(world.GetConnectDuration());

PerlScript example

$world->note($world->GetConnectDuration());

Python example

world.note(world.GetConnectDuration)

VBscript example

world.note world.GetConnectDuration

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetScriptTime (Returns the amount of time spent in script routines)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetConnectDuration)


GetCurrentValue

Script function

world.GetCurrentValue

 Read about scripting

Type

Method

Summary

Gets the current value of a named world option

Prototype

VARIANT GetCurrentValue(BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a MUSHclient <world> option, that is, the value it currently has.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

Return value

The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.

Lua example

Note (GetCurrentValue ("port"))

Note (GetCurrentValue ("player"))

Jscript example

world.note (world.GetCurrentValue ("port"));

world.note (world.GetCurrentValue ("player"));

PerlScript example

$world->note ($world->GetCurrentValue ("port"));

$world->note ($world->GetCurrentValue ("player"));

Python example

world.note (world.GetCurrentValue ("port"))

world.note (world.GetCurrentValue ("player"))

VBscript example

world.note world.GetCurrentValue ("port")

world.note world.GetCurrentValue ("player")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetCurrentValue)


GetCustomColourName

Script function

world.GetCustomColourName

 Read about scripting

Type

Method

Summary

Gets the name of a custom colour

Prototype

BSTR GetCustomColourName(short WhichColour);

 View list of data type meanings

Description

Use this to get the name of one of the 16 custom colours in the world's custom colour configuration. You must specify *which* colour you want to get/set, in the range 1 to 16.

Return value

It returns the name of the specified custom colour, or an empty string if the colour number is out of the range 1 to 16.

Lua example

Note(GetCustomColourName (5))

Jscript example

Note (GetCustomColourName (5));

PerlScript example

$world->Note($world->GetCustomColourName (5));

Python example

world.Note(world.GetCustomColourName (5))

VBscript example

Note GetCustomColourName (5)

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=GetCustomColourName)


GetDefaultValue

Script function

world.GetDefaultValue

 Read about scripting

Type

Method

Summary

Gets the default value of a named world option

Prototype

VARIANT GetDefaultValue(BSTR OptionName);

 View list of data type meanings

Description

Gets the default value of a MUSHclient <world> option, as it would be directly after creating a new world.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

Return value

The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.

Lua example

Note (GetDefaultValue ("port"))

Note (GetDefaultValue ("player"))

Jscript example

world.note (world.GetDefaultValue ("port"));

world.note (world.GetDefaultValue ("player"));

PerlScript example

$world->note ($world->GetDefaultValue ("port"));

$world->note ($world->GetDefaultValue ("player"));

Python example

world.note (world.GetDefaultValue ("port"))

world.note (world.GetDefaultValue ("player"))

VBscript example

world.note world.GetDefaultValue ("port")

world.note world.GetDefaultValue("player")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetDefaultValue)


GetDeviceCaps

Script function

world.GetDeviceCaps

 Read about scripting

Type

Method

Summary

Gets screen device capabilities

Prototype

long GetDeviceCaps(long Index);

 View list of data type meanings

Description

This asks Windows for the capability of your output screen. The index specifies which attribute you are interested in, and it returns a number corresponding to that. Some useful indices are as follows:

0 : Device driver version

2 : Device classification

4 : Horizontal size in millimeters

6 : Vertical size in millimeters

8 : Horizontal width in pixels

10 : Vertical height in pixels

12 : Number of bits per pixel

14 : Number of planes

16 : Number of brushes the device has

18 : Number of pens the device has

20 : Number of markers the device has

22 : Number of fonts the device has

24 : Number of colors the device supports

26 : Size required for device descriptor

28 : Curve capabilities

30 : Line capabilities

32 : Polygonal capabilities

34 : Text capabilities

36 : Clipping capabilities

38 : Bitblt capabilities

40 : Length of the X leg

42 : Length of the Y leg

44 : Length of the hypotenuse

45 : Shading and blending caps

88 : Logical pixels/inch in X

90 : Logical pixels/inch in Y

104 : Number of entries in physical palette

106 : Number of reserved entries in palette

108 : Actual color resolution

116 : Current vertical refresh rate of the display device (for displays only) in Hz

117 : Horizontal width of entire desktop in pixels

118 : Vertical height of entire desktop in pixels

119 : Preferred blt alignment

For more information, see:

http://www.gammon.com.au/mushclient/mw_other.htm

Return value

The value corresponding to the requested index.

Lua example

print (GetDeviceCaps (8))  --> 1920  (horizontal width)

See Also ...

Topic

 MiniWindows

Functions

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=GetDeviceCaps)


GetEntity

Script function

world.GetEntity

 Read about scripting

Type

Method

Summary

Retrieves the value of an MXP server-defined entity

Prototype

BSTR GetEntity(BSTR Name);

 View list of data type meanings

Description

Returns the value of an entity defined by the MUD server using MXP.

eg.

If the server sent:

  <!ENTITY foo "bar">

Then if you did this:

  world.Note world.GetEntity ("foo")

You would see "bar" displayed.

To get standard (automatically defined) entities use GetXMLEntity.

Return value

The contents of the specified entity, or an empty string if no such entity is found.

Lua example

Note (GetEntity ("foo"))

Jscript example

world.Note (world.GetEntity ("foo"));

PerlScript example

$world->Note (world.GetEntity ("foo"));

Python example

world.Note (world.GetEntity ("foo"))

VBscript example

world.Note world.GetEntity ("foo")

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetVariable (Gets the contents of a variable)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetEntity)


GetFrame

Script function

world.GetFrame

 Read about scripting

Type

Method

Summary

Returns the address of the main MUSHclient frame window

Prototype

long GetFrame();

 View list of data type meanings

Description

This returns the memory address of the main MUSHclient MDI frame. This is intended for advanced programmers who wish to access the MUSHclient window in their own programs.

Return value

The memory address of the main frame window.

Lua notes

In Lua the address is given as "light userdata" type. This is not particularly useful in Lua, however you can print it, and you could use it in custom-written programs.

(Help topic: function=GetFrame)


GetGlobalOption

Script function

world.GetGlobalOption

 Read about scripting

Type

Method

Summary

Gets the value of a global configuration option

Prototype

VARIANT GetGlobalOption(BSTR OptionName);

 View list of data type meanings

Description

Gets the value of an alphanumeric global option. These are global options that are not tied to a particular world.

You can use GetGlobalOptionList to get a list of the names of all possible options.

The option name is not case-sensitive. String option are returned as type BSTR (string), other options (booleans, numbers) are returned as type I4 (long). Non-existant options are returned as type EMPTY (empty).

Return value

The value of the requested option, or an "empty" variant if the option does not exist.

Lua example

Note (GetGlobalOption ("DefaultLogFileDirectory"))

Jscript example

/world.Note (world.GetGlobalOption ("DefaultLogFileDirectory"));

PerlScript example

/$world->Note ($world->GetGlobalOption ("DefaultLogFileDirectory"));

Python example

world.Note(world.GetGlobalOption ("DefaultLogFileDirectory"))

VBscript example

world.Note world.GetGlobalOption ("DefaultLogFileDirectory")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOptionList (Gets the list of global options)

 GetInfo (Gets information about the current world)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetGlobalOption)


GetGlobalOptionList

Script function

world.GetGlobalOptionList

 Read about scripting

Type

Method

Summary

Gets the list of global options

Prototype

VARIANT GetGlobalOptionList();

 View list of data type meanings

Description

Returns a variant array which is a list of all global options that you can get with GetGlobalOption. Global options are client-wide options that are not tied to a particular world.

The examples show extracting all option names, and their values.

The option names should be reasonably self-explanatory.

Return value

It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetGlobalOption" to return the value for that particular option.

Lua example

for k, v in pairs (GetGlobalOptionList()) do

  Note (v, " = ", GetGlobalOption(v))

end

Jscript example

optionlist = new VBArray(world.GetGlobalOptionList()).toArray();

 for (i = 0; i < optionlist .length; i++)

   world.note(optionlist [i] + " = " + world.GetGlobalOption (optionlist [i] ));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetGlobalOptionList))

 {

 $world->note($item . " = " . $world->GetGlobalOption($item));

 }

Python example

for opt in world.GetGlobalOptionList: world.Note (opt)

VBscript example

For Each opt In world.GetGlobalOptionList

    world.note opt + " = " + cstr (world.GetGlobalOption ( opt ))

Next

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetGlobalOptionList)


GetHostAddress

Script function

world.GetHostAddress

 Read about scripting

Type

Method

Summary

Returns a list of IP addresses that correspond to a host name on the Internet

Prototype

VARIANT GetHostAddress(BSTR HostName);

 View list of data type meanings

Description

Returns a variant array which is a list of all the TCP/IP addresses which correspond to a given IP address, using DNS (Domain Name Server).

Warning - because this function has to connect to a DNS server and await a response it may take some time to execute, perhaps 20 seconds or more.

It should not be used in a script where speed is the essence, or which is executed frequently. If you need to know the answer multiple times you should "cache" the result for future use.

The intended purpose is to relate an address in the chat system (eg. during the connection phase) to a domain name.

The reason an array is returned is because a single name might have multiple hosts (eg. Microsoft, Netscape) so a list of all of them is returned.

Return value

If there were no addresses returned then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the IP addresses for this domain name. Use "ubound" to find the number of addresses in the list.

Lua example

for k, v in pairs (GetHostAddress ("www.netscape.com")) do

  Note (v)

end

Jscript example

iplist = new VBArray(world.GetHostAddress ("www.netscape.com")).toArray();

if (iplist)  // if not empty

 for (i = 0; i < iplist.length; i++)

   Note (iplist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetHostAddress ("www.netscape.com")))

 {

 Note ($item);

 }

Python example

iplist = world.GetHostAddress ("www.netscape.com")

if (iplist ):

  for ip in iplist : world.Note (ip)

VBscript example

For Each ip In GetHostAddress ("www.netscape.com")

  Note ip

Next

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetHostAddress)


GetHostName

Script function

world.GetHostName

 Read about scripting

Type

Method

Summary

Returns the host name that corresponds to an IP address on the Internet

Prototype

BSTR GetHostName(BSTR IPaddress);

 View list of data type meanings

Description

This returns the name of the host which has a specified IP address, using DNS (Domain Name Server).

Warning - because this function has to connect to a DNS server and await a response it may take some time to execute, perhaps 20 seconds or more.

It should not be used in a script where speed is the essence, or which is executed frequently. If you need to know the answer multiple times you should "cache" the result for future use.

The address should be supplied as a "dotted decimal" string, like "66.36.226.56".

Return value

Name corresponding to the supplied IP address, or an empty string if it could not be determined.

Lua example

Note (GetHostName ("66.36.226.56"))

Jscript example

Note (GetHostName ("66.36.226.56"));

PerlScript example

Note (GetHostName ("66.36.226.56"));

Python example

world.Note (world.GetHostName ("66.36.226.56"))

VBscript example

Note GetHostName ("66.36.226.56")

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetHostName)


GetInfo

Script function

world.GetInfo

 Read about scripting

Type

Method

Summary

Gets information about the current world

Prototype

VARIANT GetInfo(long InfoType);

 View list of data type meanings

Description

Gets details about the current world. You can use:

Debug ("info")

... to list the descriptions corresponding to each one (and their current values), inside MUSHclient.

You can obtain various "types" of information about the world by specifying an "InfoType". The possible InfoTypes are:

(strings - configuration)

  1 - Server name (IP address)

  2 - World name

  3 - Character name

  4 - Send to world - file preamble

  5 - Send to world - file postamble

  6 - Send to world - line preamble

  7 - Send to world - line postamble

  8 - World notes

  9 - Sound on new activity

 10 - Scripts editor

 11 - Log file preamble

 12 - Log file postamble

 13 - Log file line preamble - player input

 14 - Log file line preamble - notes

 15 - Log file line preamble - MUD output

 16 - Log file line postamble - player input

 17 - Log file line postamble - notes

 18 - Log file line postamble - MUD output

 19 - Speed Walk Filler

 20 - Output window font name

 21 - Speed walk prefix

 22 - Text sent on connecting

 23 - Input font name

 24 - Paste to world - file preamble

 25 - Paste to world - file postamble

 26 - Paste to world - line preamble

 27 - Paste to world - line postamble

 28 - Scripting language

 29 - Script function for world open

 30 - Script function for world close

 31 - Script function for world connect

 32 - Script function for world disconnect

 31 - Script function for world get focus

 32 - Script function for world lose focus

 35 - Script file name

 36 - Scripting prefix

 37 - Auto-say string

 38 - Auto-say override

 39 - Tab-completion defaults

 40 - Auto-log file name

 41 - Recall window - line preamble

 42 - Terminal ID (telnet negotiation)

 43 - Mapping failure message

 44 - Script function for MXP starting up

 45 - Script function for MXP closing down

 46 - Script function for MXP error

 47 - Script function for MXP tag open

 48 - Script function for MXP tag close

 49 - Script function for MXP variable set

 50 - Sound to play for beeps

(strings - calculated at runtime)

 51 - Current log file name

 52 - Last "immediate" script expression

 53 - Current status line message

 54 - World file pathname

 55 - World title

 56 - MUSHclient application path name

 57 - World files default path (directory)

 58 - Log files default path (directory)

 59 - Script files default path (directory)

 60 - Plugin files default path (directory)

 61 - World TCP/IP address (as string, after DNS lookup, eg. 10.0.0.16)

 62 - Proxy server TCP/IP address (as string, after DNS lookup, eg. 10.0.0.22)

 63 - Host name (name of this PC)

 64 - Current directory

 65 - Script function for world save

 66 - MUSHclient application directory

 67 - World file directory

 68 - MUSHclient startup (initial) directory

 69 - Translation file

 70 - Locale

 71 - Font used for fixed-pitch dialogs

 72 - MUSHclient version (eg. "4.11")

 73 - MUSHclient compilation date/time (eg. "Jul 25 2007 14:21:10")

 74 - Default sounds file directory (presently GetInfo (66) + "sounds/")

 75 - Last telnet subnegotiation string received

 76 - Special font pathname

 77 - Windows version debug string (eg. "Service Pack 2")

 78 - Foreground image name

 79 - Background image name

 80 - libpng version (eg. "1.2.31")

 81 - libpng header (eg. " libpng version 1.2.31 - August 21, 2008")

 82 - Preferences database pathname

 83 - SQLite3 database version

 84 - File-browsing directory

 85 - Plugins state file directory

 86 - Word under mouse on mouse menu click

 87 - Last command sent to the MUD

(booleans - calculated at runtime)

101 - 'No Echo' flag

102 - Debug incoming packets

103 - Decompressing

104 - MXP active

105 - Pueblo active

106 - Disconnected flag (true if not connected)

107 - Currently-connecting flag

108 - OK-to-disconnect flag

109 - Trace flag

110 - Script file changed

111 - 'World file is modified' flag

112 - Automapper active flag

113 - 'World is active' flag

114 - 'Output window paused' flag

115 - Localization active

116 / 117 - removed

118 - Variables have changed

119 - Script engine is active

120 - Scoll bar is (wanted to be) visible for output window

121 - High-resolution timer is available

122 - Is the SQLite3 library thread-safe?

123 - Are we currently processing a "Simulate" function call?

124 - Is the current line from the MUD being omitted from output?

(numbers (longs) - calculated at runtime)

201 - Total lines received

202 - Lines received but not yet seen (new lines)

203 - Total lines sent

204 - Packets received

205 - Packets sent

206 - Total uncompressed bytes received

207 - Total compresssed bytes received

208 - MCCP protocol in use (0=none, 1 - or 2)

209 - MXP error count

210 - MXP tags received

211 - MXP entities received

212 - Output font height

213 - Output font width

214 - Input font height

215 - Input font width

216 - Total bytes received

217 - Total bytes sent

218 - Count of variables

219 - Count of triggers

220 - Count of timers

221 - Count of aliases

222 - Count of queued commands

223 - Count of mapper items

224 - Count of lines in output window

225 - Count of custom MXP elements

226 - Count of custom MXP entities

227 - Connect phase:

   (0=not connected, 1=MUD name lookup, 2=Proxy server name lookup,

   3=connecting to MUD, 4=connecting to proxy server, 5=proxy server phase 1,

   6=proxy server phase 2, 7=proxy server phase 3, 8=connected  to MUD)

228 - World TCP/IP address (after DNS lookup, as a number)

229 - Proxy server TCP/IP address (after DNS lookup, as a number)

230 - Script execution depth

231 - Log file size (0 if no log file open)

232 - High-performance counter output (in seconds) (double)

233 - Time spent executing trigger matching (double)

234 - Time spent executing alias matching (double)

    -  note: see GetScriptTime function for the time taken to execute scripts

235 - Number of world windows open

236 - First column of the selection in the command window (1-relative)

    - if no selection, the column to the right of the cursor.

    - If the cursor is at the start of the window, it will return 1.

237 - Last column of the selection in the command window (1-relative)

    - if no selection, returns 0.

    - For example, if "abcd" is in the command window and "bc" is selected then

    -   GetInfo (236) will return 2 and GetInfo (237) will return 3.

238 - Current "show state" for the first world window of this world.

    Hide           =  0

    Shownormal     =  1

    Normal         =  1

    Showminimized  =  2

    Showmaximized  =  3

    Maximize       =  3

    Shownoactivate =  4

    Show           =  5

    Minimize       =  6

    Showminnoactive=  7

    Showna         =  8

    Restore        =  9

    Showdefault    = 10

239 - The "source" of the current scripted action.

It is intended for scripters who want to know if a particular script is running because of user (player) action, or some sort of automated response. Effectively this can be used to determine if the player is AFK or not.

The returned value will be a number in the range 0 to 10, with these meanings:

  UnknownActionSource = 0 --> no particular reason, could be plugin saving

  UserTyping = 1 --> user typed something in the command area and pressed <Enter>

  UserMacro = 2 --> user typed a macro (eg. F2)

  UserKeypad = 3 --> user used the numeric keypad

  UserAccelerator = 4 --> user used an accelerator key

  UserMenuAction = 5 --> item chosen from pop-up menu

  TriggerFired = 6 --> trigger fired

  TimerFired = 7 --> timer fired

  InputFromServer = 8 --> input arrived (eg. packet received)

  WorldAction = 9 --> some sort of world action (eg. world open, connect, got focus)

  LuaSandbox = 10 --> executing Lua sandbox

Effectively, if GetInfo (239) returns a number in the range 1 to 5 inclusive, then the script is running in response to direct player input. Other numbers would indicate automated processing like a trigger or timer firing, input from the MUD, a plugin callback being called, and so on.

There is no entry in the list above for an alias being called, because aliases can be triggered by user input, "send to script (Execute function)", macros and so on. Thus, the number above would indicate the "real" reason an alias was called.

240 - The average width, in pixels, of a character in the output window, in the current output font. This figure is used when calculating how many characters would fit in the current width of the output window.

241 - The height, in pixels, of a character in the output window, in the current output font.

242 - Count of lines that had bad UTF-8 sequences in them, and were thus not considered for trigger evaluation (long)

243 - Font size of fixed pitch font

244 - Count of number of triggers that were evaluated (long)

245 - Count of number of triggers that matched (long)

246 - Count of number of aliases that were evaluated (long)

247 - Count of number of aliases that matched (long)

248 - Count of number of timers that fired (long)

249 - Main frame window height (long)

250 - Main frame window width (long)

251 - Main toolbar window height (long)

252 - Main toolbar window width (long)

253 - Game toolbar window height (long)

254 - Game toolbar window width (long)

255 - Activity toolbar window height (long)

256 - Activity toolbar window width (long)

257 - Info bar window height (long)

258 - Info bar window width (long)

259 - Status bar window height (long)

260 - Status bar window width (long)

261 - World window non-client height (long)

262 - World window non-client width (long)

263 - World window client height (long)

264 - World window client width (long)

265 - Windows major version  (long)  -- see below

266 - Windows minor version (long)

267 - Windows build number (long)

268 - Windows platform ID (long)

269 - Foreground image mode

270 - Background image mode

271 - Background colour

272 - Text rectangle - left  (see TextRectangle function)

273 - Text rectangle - top

274 - Text rectangle - right

275 - Text rectangle - bottom

276 - Text rectangle - border offset

277 - Text rectangle - border width

278 - Text rectangle - outside colour

279 - Text rectangle - outside style

280 - Output window client height

281 - Output window client width

282 - Text rectangle - border colour

283 - Mouse position - X (relative to world output window)

284 - Mouse position - Y

285 - Is output window available? (true or false)

286 - Triggers matched this session (long)

287 - Aliases matched this session (long)

288 - Timers fired this session  (long)

289 - Last line number that was terminated by an IAC/GA or IAC/EOR (long)

290 - Actual text rectangle - left  (see below)

291 - Actual text rectangle - top

292 - Actual text rectangle - right

293 - Actual text rectangle - bottom

294 - Status of keyboard modifiers / mouse click, as follows:

      (values are in hexadecimal)

      0x00001 - shift key down (left or right)

      0x00002 - control key down (left or right)

      0x00004 - Alt key down (left or right)

      0x00008 - left shift key down

      0x00010 - right shift key down

      0x00020 - left control key down

      0x00040 - right control key down

      0x00080 - left Alt key down

      0x00100 - right Alt key down

      0x00200 - Caps Lock key down (right now)

      0x00400 - Num Lock key down (right now)

      0x00800 - Scroll Lock key down (right now)

      0x02000 - Caps Lock key toggled (active)

      0x04000 - Num Lock key  toggled (active)

      0x08000 - Scroll Lock key  toggled (active)

      0x10000 - Left mouse button down

      0x20000 - Right mouse button down

      0x40000 - Middle mouse button down

More than one of these can be active at once so you should use a bitwise "and"

operation to check each bit (eg. bit.band in Lua).

295 - Number of times output window was redrawn

296 - Current vertical position of scroll bar in first output window (long)

297 - Resolution (frequency) of the high-resolution timer

298 - SQLite3 version number (eg. 3007002 for version 3.7.2.)

299 - ANSI code-page number (see below)

300 - OEM code-page number (see below)

(dates - calculated at runtime)

301 - Time connected

302 - Time log file was last flushed to disk

303 - When script file was last modified

304 - The current date/time

305 - When client started executing

306 - When this world was created/opened

(more numbers)

310 - Newlines received from the MUD (lines terminated by a newline)

You can deduce the operating system as follows by using GetInfo (265) through to GetInfo (268):

If platform ID == 0 (Win32s) then:

  you should not get this, MUSHclient doesn't run under Win32s

If platform ID == 1 (Windows 95-style versions) then:

If major == 4 and minor == 0 then: Windows 95

If major == 4 and minor == 10 then: Windows 98 (or 98SE)

If major == 4 and minor == 90 then: Windows ME

If platform ID == 2 (Windows NT versions) then:

If major == 3 then: Windows NT 3.51

If major == 4 then: Windows NT 4

If major == 5 and minor == 0 then: Windows 2000

If major == 5 and minor == 1 then: Windows XP

If major == 5 and minor == 2 then: Windows Server 2003

If major == 6 and minor == 0 then: Windows Vista, or Windows Server Longhorn

If major == 6 and minor == 1 then: Windows 7

If major == 6 and minor == 2 then: Windows 8

If major == 6 and minor == 3 then: Windows 8.1

If major == 10 and minor == 0 then: Windows 10

(The symbol "==" means "is equal to").

----

The "actual text rectangle" (selectors 290 to 293) give the offset of the text rectangle inside the main output window, taking into account the TextRectangle function (if used). However unlike selectors 273 to 276 these will always be the correct pixel offsets. For example, if TextRectangle has never been called, then 273 to 276 will all be zero, whereas 290 to 293 will have the coordinates of the text rectangle. Also if negative offsets are used for the bottom or right sides, then these are "normalized" into actual offsets for selectors 290 to 293. Thus you can use 290 to 293 for finding exactly where the text is on the screen (these figures may change if the window is resized).

----

ANSI code page numbers:

874 Thai

932 Japan

936 Chinese (PRC, Singapore)

949 Korean

950 Chinese (Taiwan Region; Hong Kong SAR, PRC)

1200 Unicode (BMP of ISO 10646)

1250 Windows 3.1 Eastern European

1251 Windows 3.1 Cyrillic

1252 Windows 3.1 Latin 1 (US, Western Europe)

1253 Windows 3.1 Greek

1254 Windows 3.1 Turkish

1255 Hebrew

1256 Arabic

1257 Baltic

OEM code page numbers:

437 MS-DOS United States

708 Arabic (ASMO 708)

709 Arabic (ASMO 449+, BCON V4)

710 Arabic (Transparent Arabic)

720 Arabic (Transparent ASMO)

737 Greek (formerly 437G)

775 Baltic

850 MS-DOS Multilingual (Latin I)

852 MS-DOS Slavic (Latin II)

855 IBM Cyrillic (primarily Russian)

857 IBM Turkish

860 MS-DOS Portuguese

861 MS-DOS Icelandic

862 Hebrew

863 MS-DOS Canadian-French

864 Arabic

865 MS-DOS Nordic

866 MS-DOS Russian (former USSR)

869 IBM Modern Greek

874 Thai

932 Japan

936 Chinese (PRC, Singapore)

949 Korean

950 Chinese (Taiwan Region; Hong Kong SAR, PRC)

1361 Korean (Johab)

Return value

The specified information about the world, as described above.

An EMPTY variant, if a date is undefined.

A NULL variant if the InfoType is not a valid type.

Lua example

--

--  display all information

--

for i = 1, 320 do

  info = GetInfo(i)

  if info then

    Note (i, " = ", info)

  end

end

Jscript example

//

//  display all information

//

for (i = 1; i <= 320; i++)

  {

  info = world.GetInfo (i);

  if (info)

    world.Note (i + " = " + info);

  }

PerlScript example

#

#  Display world IP address

#

$world->note ($world->GetInfo (1));

Python example

#

#  display all information

#

for i in range (320):

  info = world.GetInfo (i)

  if (info):

    world.Note (str(i) + " = " + str(info))

VBscript example

'

'  List the lot

'

dim i, info

for i = 1 to 320

  info = world.GetInfo (i)

  if not isnull (info) then

   world.note i & " = " & info

  end if

next

'

' Find world IP address

'

Note GetInfo (1)

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetAliasInfo (Gets details about an alias)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetTimerInfo (Gets details about a timer)

 GetTriggerInfo (Gets details about a named trigger)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetInfo)


GetInternalCommandsList

Script function

world.GetInternalCommandsList

 Read about scripting

Type

Method

Summary

Returns a list of the internal MUSHclient command names

Prototype

VARIANT GetInternalCommandsList();

 View list of data type meanings

Description

This returns a variant array of the internal MUSHclient command names. You can use any name in this list in the DoCommand function. You can also use:

/world.Debug "internal_commands"

to see the list shown in the output window.

Return value

It returns a variant array containing the names of the internal MUSHclient commands. Use "ubound" to find the number of commands in the list.

Lua example

for k, v in pairs (GetInternalCommandsList ()) do

  Note (v)

end

Jscript example

commandList = new VBArray(world.GetInternalCommandsList ()).toArray();

  for (i = 0; i < commandList.length; i++)

      Note (commandList [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetInternalCommandsList()))

 {

 $world->note($item);

 }

Python example

for c in world.GetInternalCommandsList  : world.Note (c)

VBscript example

For Each command In GetInternalCommandsList

    world.Note command

  Next

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 DoCommand (Queues a MUSHclient menu command)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetInternalCommandsList)


GetLineCount

Script function

world.GetLineCount

 Read about scripting

Type

Method

Summary

Gets count of lines received

Prototype

long GetLineCount();

 View list of data type meanings

Description

This returns the number of lines received by this world. However, see GetLinesInBufferCount for the number of lines currently in the output buffer, which might be different.

Return value

The number of lines received by this world.

Lua example

Note(GetLineCount())

Jscript example

world.note(world.GetLineCount());

PerlScript example

$world->note($world->GetLineCount());

Python example

world.note(world.GetLineCount)

VBscript example

world.note world.GetLineCount

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetLineCount)


GetLineInfo

Script function

world.GetLineInfo

 Read about scripting

Type

Method

Summary

Gets details about a specified line in the output window

Prototype

VARIANT GetLineInfo(long LineNumber, short InfoType);

 View list of data type meanings

Description

Returns details about any line in the output buffer (window).

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window. This number is different from the sequential number of the line since the world opened. For example, if your buffer size is 5000 lines, and you have received 8000 lines, then the last line will be line around 5000 in the buffer but "actual line number" (selector 10 below) will return 8000.

Note that when the buffer fills up lines are discarded in batches of 100, so the last line will probably not be 5000, even if your buffer size is 5000 and you have been connected for a while. It is likely to be in the range 4900 to 4999.

Also, the last line may be blank (empty) as MUSHclient creates a new, empty, line as soon as a newline is received for the previous line from the MUD.

You can obtain one of 12 "types" of information about the line by specifying an "InfoType". The possible InfoTypes are:

 1: text of line (string)

 2: length of text (short)

 3: true if newline, false if not  (boolean)

 4: true if world.note  (boolean)

 5: true if player input (boolean)

 6: true if line logged  (boolean)

 7: true if bookmarked  (boolean)

 8: true if MXP horizontal rule (<hr>)  (boolean)

 9: date/time line arrived  (date)

10: actual line number (not line number in buffer)  (long)

11: count of style runs  (long)

12: ticks - exact value from the high-performance timer (double)

13: elapsed time in seconds from when the world was started (opened) (high precision)

The text of the line is the actual text you see on the screen.

If "newline" is true then this line is the end of a paragraph (ie. had a newline at the end of it). You can reassemble paragraphs by concatenating lines as found, and then adding a newline (carriage-return, linefeed) whenever "newline" is true. MUSHclient automatically preserves the space at the end of each line, so it is unnecessary to add another of your own. If "indent paragraphs" option is set in MUSHclient the space will be at the start of the next line, rather than the end of the previous line.

If "world.note" is true this is a "note" line, not MUD output.

If "player input" is true, then this line is an echoed command, not MUD output.

The count of styles runs can be used in conjunction with GetStyleInfo to further break up individual lines into style runs (eg. colour changes, bold, underline, etc.).

The "ticks" value is obtained by querying the "high performance timer" provided by Windows. This gives a time interval to a high degree of precision, however it is not related to the time-of-day in any meaningful way. The intention here is that you can use it to find the precise time difference between various lines as they arrive from the MUD.

Return value

The specified information about the line, as described above.

An EMPTY variant, if the line does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

local line, total_lines

total_lines = GetLinesInBufferCount ()

--

--  Example showing the last 10 lines in the output buffer

--   Shown is text of line, date/time received, count of style runs

--

for line = total_lines - 10, total_lines do

  Note ("Line ", line, " = ", GetLineInfo (line, 1))

  Tell ("Received ", GetLineInfo (line, 9))

  Note (" - Style runs = ", GetLineInfo (line, 11))

  end

-- Lua extension - returns all information in a table:

for line = total_lines - 10, total_lines do

  table.foreach (GetLineInfo (line), print)

end

Lua notes

The InfoType is optional, and defaults to zero.

As an extension, if the InfoType is omitted or zero, then all types of information

for the nominated line are returned in a table, keyed by type:

 text:     text of line (string)

 length:   length of text (number)

 newline:  true if newline, false if not  (boolean)

 note:     true if world.note  (boolean)

 user:     true if player input (boolean)

 log:      true if line logged  (boolean)

 bookmark: true if bookmarked  (boolean)

 hr:       true if MXP horizontal rule (<hr>)  (boolean)

 time:     date/time line arrived  (date - number)

 timestr:  date/time line arrived  (date - string)

 line:     actual line number (not line number in buffer)  (number)

 styles:   count of style runs  (number)

 ticks:    exact value from the high-performance timer

(number)

 elapsed:  exact elapsed time (number) since world started (opened)

Thus, to print the text of line 5 you might do this:

  print (GetLineInfo (5).text)

If the line does not exist, or the InfoType is invalid, Lua will return nil.

Jscript example

var line, total_lines;

total_lines = world.GetLinesInBufferCount ();

//

//  Example showing the last 10 lines in the output buffer

//   Shown is text of line, date/time received, count of style runs

//

for (line = total_lines - 10; line <= total_lines; line++)

  {

  world.note ("Line " + line + " = " + world.GetLineInfo (line, 1));

  world.tell ("Received " + world.GetLineInfo (line, 9));

  world.note (" - Style runs = " + world.GetLineInfo (line, 11));

  }

PerlScript example

my $line, $total_lines;

$total_lines = $world->GetLinesInBufferCount ();

#

#  Example showing the last 10 lines in the output buffer

#   Shown is text of line, date/time received, count of style runs

#

for ($line = $total_lines - 10; $line <= $total_lines; $line++)

  {

  $world->note ("Line " . $line . " = " . $world->GetLineInfo ($line, 1));

  $world->tell ("Received " . $world->GetLineInfo ($line, 9));

  $world->note (" - Style runs = " . $world->GetLineInfo ($line, 11));

  }

Python example

total_lines = world.GetLinesInBufferCount

#

#  Example showing the last 10 lines in the output buffer

#   Shown is text of line, date/time received, count of style runs

#

for line in range (total_lines - 10, total_lines):

  world.note ("Line " + str(line) + " = " + world.GetLineInfo (line, 1))

  world.tell ("Received " + str (world.GetLineInfo (line, 9)))

  world.note (" - Style runs = " + str (world.GetLineInfo (line, 11)))

VBscript example

dim line, total_lines

total_lines = world.GetLinesInBufferCount

'

'  Example showing the last 10 lines in the output buffer

'   Shown is text of line, date/time received, count of style runs

'

for line = total_lines - 10 to total_lines

  world.note "Line " & line & " = " & world.GetLineInfo (line, 1)

  world.tell "Received " & world.GetLineInfo (line, 9)

  world.note " - Style runs = " & world.GetLineInfo (line, 11)

next

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetLineInfo)


GetLinesInBufferCount

Script function

world.GetLinesInBufferCount

 Read about scripting

Type

Method

Summary

Returns the number of lines in the output window

Prototype

long GetLinesInBufferCount();

 View list of data type meanings

Description

This returns the number of lines in the output buffer (window) of this world.

It will differ from GetLineCount once the number of lines received exceeds the size of the buffer (as early ones will be discarded).

Return value

The number of lines in the output buffer (output window) of this world.

Lua example

Note(GetLinesInBufferCount())

Jscript example

world.note(world.GetLinesInBufferCount());

PerlScript example

$world->note($world->GetLinesInBufferCount());

Python example

world.note(world.GetLinesInBufferCount)

VBscript example

world.note world.GetLinesInBufferCount

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetLinesInBufferCount)


GetLoadedValue

Script function

world.GetLoadedValue

 Read about scripting

Type

Method

Summary

Gets value of a named world option, as loaded from the world file

Prototype

VARIANT GetLoadedValue(BSTR OptionName);

 View list of data type meanings

Description

Gets the value of a MUSHclient <world> option, as at the moment after the world was loaded from disk.

You can use GetOptionList, and GetAlphaOptionList, to get a list of the names of all possible options.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

Return value

The value of the requested option, or a NULL variant if the option does not exist, or is not permitted to be read.

Lua example

Note (GetLoadedValue ("port"))

Note (GetLoadedValue ("player"))

Jscript example

world.note (world.GetLoadedValue ("port"));

world.note (world.GetLoadedValue ("player"));

PerlScript example

$world->note ($world->GetLoadedValue ("port"));

$world->note ($world->GetLoadedValue ("player"));

Python example

world.note (world.GetLoadedValue ("port"))

world.note (world.GetLoadedValue ("player"))

VBscript example

world.note world.GetLoadedValue ("port")

world.note world.GetLoadedValue ("player")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetLoadedValue)


GetMainWindowPosition

Script function

world.GetMainWindowPosition

 Read about scripting

Type

Method

Summary

Returns the position and size of the main MUSHclient window

Prototype

BSTR GetMainWindowPosition();

 View list of data type meanings

Description

This function returns the size of the main MUSHclient window (the frame window inside which all world windows reside), in pixels.

For normal scripting languages these return a string, like this: "89,18,825,654". For Lua, see below.

Return value

Returns a string in the form:

left,top,width,height

eg. "89,18,825,654"

For Lua, returns a table containing:

top=(value)

height=(value)

left=(value)

width=(value)

Lua example

table.foreach (GetMainWindowPosition (), print)

Lua notes

In Lua it returns a table with four entries, like this:

top=18

height=654

left=89

width=825

In Lua you can supply an optional boolean argument. If true, a different method of calculating the window position is used (calling GetWindowRect rather than GetWindowPlacement). This method gives a more accurate result if you use "Aero Snap" under Windows 7 or higher. However it may return inaccurate results if the window is minimized.

eg.

GetMainWindowPosition (true)

The default is false, the original behaviour.

Jscript example

Note (GetMainWindowPosition ())

VBscript example

Note GetMainWindowPosition

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetMainWindowPosition)


GetMapColour

Script function

world.GetMapColour

 Read about scripting

Type

Method

Summary

Returns the mapping for how a particular colour will be displayed

Prototype

long GetMapColour(long Which);

 View list of data type meanings

Description

Returns the RGB code for how a particular colour is going to be displayed.

Return value

The RGB code corresponding to the colour in the colour mapping table. If the colour is not present, the supplied argument will be returned.

Lua example

colour = MapColour (ColourNameToRGB ("red"))

Jscript example

colour = MapColour (ColourNameToRGB ("red"))

VBscript example

colour = MapColour (ColourNameToRGB ("red"))

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=GetMapColour)


GetMappingCount

Script function

world.GetMappingCount

 Read about scripting

Type

Method

Summary

Gets a count of the number of items in the auto-map sequence

Prototype

long GetMappingCount();

 View list of data type meanings

Description

Returns the number of items in the auto-map sequence. May be zero if no items are present.

Return value

The number of items in the auto-map sequence. Will be zero if it is empty.

Lua example

Note (GetMappingCount ())

Jscript example

world.note(world.GetMappingCount);

PerlScript example

$world->note ($world->GetMappingCount);

Python example

world.note(world.GetMappingCount)

VBscript example

world.note world.GetMappingCount

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=GetMappingCount)


GetMappingItem

Script function

world.GetMappingItem

 Read about scripting

Type

Method

Summary

Gets one item from the auto-map sequence

Prototype

VARIANT GetMappingItem(long Item);

 View list of data type meanings

Description

Returns one item from the auto-map sequence. You supply the item number that you want.

It should be in the range zero to the value returned by GetMappingCount, minus 1. If not, a NULL variant will be returned.

The item number is zero relative, so that if you have two items in the map sequence, they will be:

0: first item

1: second item

The returned value is a single string, with the forwards and reverse direction separated by a slash. For example:

north/south

Return value

If the item number is less than zero, or greater than, or equal to, the number returned by GetMappingCount, then a NULL variant will be returned.

Otherwise, the contents of the appropriate map item will be returned. The forwards and reverse direction will be separated by the "/" character.

Lua example

Note(GetMappingItem(0))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

world.note(world.GetMappingItem(0));

PerlScript example

$world->note($world->GetMappingItem(0));

Python example

world.note(world.GetMappingItem(0))

VBscript example

world.note world.GetMappingItem (0)

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=GetMappingItem)


GetMappingString

Script function

world.GetMappingString

 Read about scripting

Type

Method

Summary

Returns the speedwalk string generated by the auto-mapper.

Prototype

VARIANT GetMappingString();

 View list of data type meanings

Description

Returns the speedwalk string generated by the auto-mapper. This is a string that can be sent to EvaluateSpeedWalk to convert it into appropriate commands for sending to the MUD.

For example:

4s 2(ne/sw) e (ne/sw) 2n

If you want to get the reverse direction , send the supplied string to ReverseSpeedwalk.

Return value

The speedwalk string generated by the auto-mapper. It might be an empty string if there are no items in the auto-map sequence.

Lua example

Note(GetMappingString())

Jscript example

world.note(world.GetMappingString());

PerlScript example

$world->note($world->GetMappingString());

Python example

world.note(world.GetMappingString)

VBscript example

world.note world.GetMappingString

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 EvaluateSpeedwalk (Evaluates a speed walk string)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

 ReverseSpeedwalk (Reverses a speed walk string)

(Help topic: function=GetMappingString)


GetNotepadLength

Script function

world.GetNotepadLength

 Read about scripting

Type

Method

Summary

Gets the length of the text in a notepad window

Prototype

long GetNotepadLength(BSTR Title);

 View list of data type meanings

Description

Find the length of the text in the specified notepad window.

If a notepad of that name does not exist a length of zero is returned.

Return value

The length of the text in the specified notepad, in characters.

If that notepad does not exist, zero is returned.

Lua example

Note (GetNotepadLength ("mynotes"))

Jscript example

world.Note (world.GetNotepadLength ("mynotes"));

PerlScript example

Note (GetNotepadLength ("mynotes"));

Python example

world.Note (str (world.GetNotepadLength ("mynotes")));

VBscript example

world.Note world.GetNotepadLength ("mynotes")

See Also ...

Topic

 Notepad

Functions

 Activate (Activates the world window)

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=GetNotepadLength)


GetNotepadList

Script function

world.GetNotepadList

 Read about scripting

Type

Method

Summary

Gets the list of open notepads - returning their titles

Prototype

VARIANT GetNotepadList(boolean All);

 View list of data type meanings

Description

Returns a variant array which is a list of all open notepad windows.

If more than one notepad has the same title you may get duplicates.

If the argument (All) is true, then all notepad windows for the MUSHclient application are returned.

If the argument is false, then only "related" notepads for the current world are returned. Related notepads are those created from the world (eg. by AppendToNotepad), and are not ones manually created (eg. by the player).

Note that most notepad-related functions only apply to related notepads - that is, ones that "belong" to the world calling them.

Return value

If there are no notepads open then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the titles of all the notepads. Use "ubound" to find the number of notepads in the list.

Lua example

for k, v in pairs (GetNotepadList()) do

  Note (v)

end

Lua notes

The argument "All" is optional, and defaults to false.

Jscript example

notepadlist = new VBArray(world.GetNotepadList()).toArray();

if (notepadlist )  // if not empty

 for (i = 0; i < notepadlist.length; i++)

   world.note(notepadlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetNotepadList))

 {

 $world->note($item);

 }

Python example

notepadlist = world.GetNotepadList

if (notepadlist):

  for w in notepadlist : world.Note (w)

VBscript example

for each name in world.GetNotepadList

  world.Note name

next

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=GetNotepadList)


GetNotepadText

Script function

world.GetNotepadText

 Read about scripting

Type

Method

Summary

Gets the text from a notepad window

Prototype

BSTR GetNotepadText(BSTR Title);

 View list of data type meanings

Description

Returns the text from the specified notepad window.

If a notepad of that name does not exist an empty string is returned.

Return value

The text from the specified notepad window.

If that notepad does not exist, an empty string is returned.

Lua example

Note (GetNotepadText ("mynotes"))

Jscript example

world.Note (world.GetNotepadText ("mynotes"));

PerlScript example

Note (GetNotepadText ("mynotes"));

Python example

world.Note (world.GetNotepadText ("mynotes"))

VBscript example

world.Note world.GetNotepadText("mynotes")

See Also ...

Topic

 Notepad

Functions

 Activate (Activates the world window)

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=GetNotepadText)


GetNotepadWindowPosition

Script function

world.GetNotepadWindowPosition

 Read about scripting

Type

Method

Summary

Returns the position and size of the specified notepad window

Prototype

BSTR GetNotepadWindowPosition(BSTR Title);

 View list of data type meanings

Description

This function returns the size of the specified notepad's window, in pixels.

For normal scripting languages these return a string, like this: "66,66,637,356". For Lua, see below.

Return value

Returns a string in the form:

left,top,width,height

eg. "66,66,637,356"

For Lua, returns a table containing:

top=(value)

height=(value)

left=(value)

width=(value)

If the nominated notepad window does not exist, returns the empty string.

In Lua, if the notepad window does not exist, returns nil.

Lua example

table.foreach (GetNotepadWindowPosition ("my_notepad"), print)

Lua notes

In Lua it returns a table with four entries, like this:

top 66

height 356

left 66

width 637

If the notepad window does not exist, returns nil.

Jscript example

Note (GetNotepadWindowPosition ("my_notepad"))

VBscript example

Note GetNotepadWindowPosition ("my_notepad")

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetNotepadWindowPosition)


GetNotes

Script function

world.GetNotes

 Read about scripting

Type

Method

Summary

Gets the world's notes

Prototype

BSTR GetNotes();

 View list of data type meanings

Description

This returns the notes for the current world.

See also SetNotes.

Return value

Notes for current world.

Lua example

Note(GetNotes())

Jscript example

world.note(world.GetNotes());

PerlScript example

$world->note($world->GetNotes());

Python example

world.note(world.GetNotes)

VBscript example

world.note world.getnotes

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 SetNotes (Sets the notes for the world.)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetNotes)


GetNoteStyle

Script function

world.GetNoteStyle

 Read about scripting

Type

Method

Summary

Gets the style for notes

Prototype

short GetNoteStyle();

 View list of data type meanings

Description

This gets the text style for world.note and similar functions.

The styles are 1 bit each, which can be added or OR'ed together.

The style bits are:

  1 = bold

  2 = underline

  4 = blink (italic)

  8 = inverse

 32 = strike-through

Return value

The style currently in force for notes.

Lua example

Note (GetNoteStyle ())

Jscript example

Note (GetNoteStyle ());

PerlScript example

Note (GetNoteStyle ());

Python example

Note (GetNoteStyle ())

VBscript example

Note GetNoteStyle

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=GetNoteStyle)


GetOption

Script function

world.GetOption

 Read about scripting

Type

Method

Summary

Gets value of a named world option

Prototype

long GetOption(BSTR OptionName);

 View list of data type meanings

Description

Gets value of a world option. Many options are booleans (true or false). The number zero represents false (option not set) and the number one represents true (option set).

You can use GetOptionList to get a list of the names of all possible options.

Return value

The value of the requested option, or -1 if the option does not exist.

Lua example

Note (GetOption ("show_italic"))

Jscript example

/world.note(world.getoption ("show_italic"));

PerlScript example

/$world->note ($world->getoption ("show_italic"));

Python example

world.note(world.getoption ("show_italic"))

VBscript example

world.note world.getoption ("show_italic")

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetOption)


GetOptionList

Script function

world.GetOptionList

 Read about scripting

Type

Method

Summary

Gets the list of world options

Prototype

VARIANT GetOptionList();

 View list of data type meanings

Description

Returns a variant array which is a list of all options that you can get with GetOption or set with SetOption.

The examples show extracting all option names, and their values.

The option names should be reasonably self-explanatory.

Return value

It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetOption" to return the value for that particular option, or "SetOption" to set that option value.

Lua example

for k, v in pairs (GetOptionList()) do

  Note (v, " = ", GetOption (v))

end

Jscript example

optionlist = new VBArray(world.GetOptionList()).toArray();

 for (i = 0; i < optionlist .length; i++)

   world.note(optionlist [i] + " = " + world.GetOption (optionlist [i] ));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetOptionList))

 {

 $world->note($item . " = " . $world->GetOption($item));

 }

Python example

for opt in world.GetOptionList: world.Note (opt)

VBscript example

For Each opt In world.GetOptionList

    world.note opt + " = " + cstr (world.GetOption ( opt ))

Next

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=GetOptionList)


GetPluginAliasInfo

Script function

world.GetPluginAliasInfo

 Read about scripting

Type

Method

Summary

Gets details about a named alias for a specified plugin

Prototype

VARIANT GetPluginAliasInfo(BSTR PluginID, BSTR AliasName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified alias for the specified plugin.

You can obtain various "types" of information about the alias by specifying an "InfoType". The possible InfoTypes are described under GetAliasInfo.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a alias in the current plugin, use "GetAliasInfo".

If you are writing a plugin and want to find "global" MUSHclient alias values, use an empty plugin ID, eg.

  world.Note world.GetPluginAliasInfo ("", "my_alias", 1)

Return value

The specified information about the alias, as described above.

An EMPTY variant, if the alias does not exist.

A NULL variant if the alias name is invalid.

A NULL variant if the InfoType is not a valid type.

A NULL variant if the plugin is not installed.

Lua example

Note (GetPluginAliasInfo  ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

world.note(world.GetPluginAliasInfo  ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2));

PerlScript example

/$world->note ($world->GetPluginAliasInfo  ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2));

Python example

world.note(world.GetPluginAliasInfo  ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2))

VBscript example

world.note world.GetPluginAliasInfo ("c8efc9f9e1edd118c6f2dbf5", "my_alias", 2)

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetPluginAliasInfo)


GetPluginAliasList

Script function

world.GetPluginAliasList

 Read about scripting

Type

Method

Summary

Gets the list of aliases in a specified plugin

Prototype

VARIANT GetPluginAliasList(BSTR PluginID);

 View list of data type meanings

Description

Returns an array of all the named aliases currently defined for the nominated plugin. You can then use GetPluginAliasInfo to find out more details about each one.

If you want to find the list of aliases in the current plugin, use "GetAliasList".

If you are writing a plugin and want to find the "global" MUSHclient alias list, use an empty plugin ID, eg.

 alList = world.GetPluginAliasList ("")

Return value

If there are no aliases (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the aliases in the specified plugin. Use "ubound" to find the number of aliases in the list. You can then use "GetPluginAliasInfo" to find details about each alias.

Lua example

for k, v in pairs (GetPluginAliasList ("982581e59ab42844527eec80")) do

  Note (v)

end

Jscript example

aliaslist = new VBArray(world.GetPluginAliasList("982581e59ab42844527eec80")).toArray();

if (aliaslist)  // if not empty

 for (i = 0; i < aliaslist.length; i++)

   world.note(aliaslist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetPluginAliasList ("982581e59ab42844527eec80")))

 {

 $world->note($item);

 }

Python example

aliaslist = world.GetPluginAliasList ("982581e59ab42844527eec80")

if (aliaslist):

  for a in aliaslist : world.Note (a)

VBscript example

dim alList

alList = world.GetPluginAliasList ("982581e59ab42844527eec80")

If Not IsEmpty (alList) Then

  for each a in alList

    world.note a

  next

End If

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetPluginAliasList)


GetPluginAliasOption

Script function

world.GetPluginAliasOption

 Read about scripting

Type

Method

Summary

Gets the value of a named alias option for a specified plugin

Prototype

VARIANT GetPluginAliasOption(BSTR PluginID, BSTR AliasName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of an alias option for the specified plugin.

You must specify a plugin ID, the name of an existing alias, and an alias option from the list given under the description for GetAliasOption. These are the same names as used in the XML world files for alias options.

If you want to find the value of an alias option in the current plugin, use "GetAliasOption".

If you are writing a plugin and want to find "global" MUSHclient alias values, use an empty plugin ID, eg.

  world.Note world.GetPluginAliasOption ("", "my_alias", "enabled")

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See GetAliasOption for a list of option names and values.

Return value

As described above.

Lua example

Note (GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

Note (GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"));

PerlScript example

/$world->Note ($world->GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"));

Python example

world.Note(world.GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"))

VBscript example

Note GetPluginAliasOption("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match")

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 IsAlias (Tests to see if an alias exists)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=GetPluginAliasOption)


GetPluginID

Script function

world.GetPluginID

 Read about scripting

Type

Method

Summary

Returns the 24-character ID of the current plugin

Prototype

BSTR GetPluginID();

 View list of data type meanings

Description

Returns the unique ID (identifier) of the currently-executing plugin. This will let the plugin find things out about itself (using GetPluginInfo). If no plugin is executing an empty string will be returned.

To find the unique ID of your current world (rather than plugin) use GetWorldID.

Return value

The 24-character plugin ID of the current plugin, or an empty string if no plugin is running.

Lua example

Note (GetPluginID ())

Jscript example

world.Note (world.GetPluginID ());

PerlScript example

$world->Note ($world->GetPluginID ());

Python example

world.Note (world.GetPluginID )

VBscript example

world.Note world.GetPluginID

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetWorldID (Returns the 24-character ID of the current world)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginID)


GetPluginInfo

Script function

world.GetPluginInfo

 Read about scripting

Type

Method

Summary

Gets details about a specified plugin

Prototype

VARIANT GetPluginInfo(BSTR PluginID, short InfoType);

 View list of data type meanings

Description

Gets details about the specified plugin, identified by its unique ID.

You can obtain various "types" of information about the plugin by specifying an "InfoType".

If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsNull" to test for this possibility).

You can obtain one of 25 "types" of information about the plugin by specifying an "InfoType". The possible InfoTypes are:

 1: Name (string)

 2: Author (string)

 3: Description (long description) (string)

 4: Script contents (string)

 5: Script language (ie. vbscript, perlscript, jscript) (string)

 6: Plugin file name (string)

 7: Unique ID (string)

 8: Purpose (short description) (string)

 9: Number of triggers (long)

10: Number of aliases (long)

11: Number of timers (long)

12: Number of variables (long)

13: Date written (date)

14: Date modified (date)

15: Save state flag (boolean)

16: Scripting enabled? (boolean)

17: Enabled? (boolean)

18: Required MUSHclient version (double)

19: Version of plugin (double)

20: Directory that plugin resides in (string)

21: Evaluation order of plugin (long)

22: Date/time plugin installed (date)

23: During a CallPlugin call, the ID of the calling plugin (if any) (string)

24: Time spent on scripting in this plugin (seconds, double)

25: Plugin sequence number (short)

The evaluation order starts at 1, and increases by 1 for each plugin in the list of plugins (disabled or not).

Return value

The specified information about the plugin, as described above.

A NULL variant if the InfoType is not a valid type.

A NULL variant if the plugin is not installed.

Lua example

Note (GetPluginInfo (GetPluginID (), 8))

Jscript example

world.note (world.GetPluginInfo (world.GetPluginID, 8));

PerlScript example

$world->note ($world->GetPluginInfo ($world->GetPluginID, 8));

Python example

world.note (world.GetPluginInfo (world.GetPluginID, 8))

VBscript example

world.note world.GetPluginInfo (world.GetPluginID, 8)

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginInfo)


GetPluginList

Script function

world.GetPluginList

 Read about scripting

Type

Method

Summary

Gets a list of installed plugins.

Prototype

VARIANT GetPluginList();

 View list of data type meanings

Description

Returns an array of the unique IDs of all the plugins currently installed.

Return value

If there are no plugins then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the unique IDs of all the plugins. Use "lbound" and "ubound" to find the bounds of the array of plugins (ie. the number of plugins in the list). You can then use "GetPluginInfo" to find information about each plugin.

Lua example

for k, v in pairs (GetPluginList()) do

  Note (v, " = ", GetPluginInfo(v, 1))

end

Jscript example

pluginlist = new VBArray(world.GetPluginList()).toArray();

if (pluginlist)  // if not empty

  for (i = 0; i < pluginlist.length; i++)

      world.note(pluginlist [i] + " = " +

                 world.GetPluginInfo(pluginlist [i], 1));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetPluginList))

   {

   ($key, $value) = ($item, $world->GetPluginInfo ($item, 1));

   $world->note($key . " = " . $value) if (defined ($key));

   }

Python example

pluginlist = world.GetPluginList

if (pluginlist):

  for p in pluginlist: world.Note (p + " = " +

                  world.GetPluginInfo(p, 1))

VBscript example

dim pluginList

pluginList = world.GetPluginList

If Not IsEmpty (pluginList) Then

  For Each p In pluginList

     world.note p & " = " &  world.GetPluginInfo (p, 1)

  Next

End If

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginList)


GetPluginName

Script function

world.GetPluginName

 Read about scripting

Type

Method

Summary

Returns the name of the current plugin

Prototype

BSTR GetPluginName();

 View list of data type meanings

Description

Returns the name of the currently-executing plugin. If no plugin is executing an empty string will be returned.

Return value

The name of the current plugin, or an empty string if no plugin is running.

Lua example

Note (GetPluginName ())

Jscript example

world.Note (world.GetPluginName ());

PerlScript example

$world->Note ($world->GetPluginName ());

Python example

world.Note (world.GetPluginName )

VBscript example

world.Note world.GetPluginName

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginName)


GetPluginTimerInfo

Script function

world.GetPluginTimerInfo

 Read about scripting

Type

Method

Summary

Gets details about a named timer for a specified plugin

Prototype

VARIANT GetPluginTimerInfo(BSTR PluginID, BSTR TimerName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified timer for the specified plugin.

You can obtain various "types" of information about the timer by specifying an "InfoType". The possible InfoTypes are described under GetTimerInfo.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a timer in the current plugin, use "GetTimerInfo".

If you are writing a plugin and want to find "global" MUSHclient timer values, use an empty plugin ID, eg.

  world.Note world.GetPlugintimerInfo ("", "my_timer", 1)

Return value

The specified information about the timer, as described above.

An EMPTY variant, if the timer does not exist.

A NULL variant if the timer name is invalid.

A NULL variant if the InfoType is not a valid type.

A NULL variant if the plugin is not installed.

Lua example

Note(GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

world.note(world.GetPluginTimerInfo   ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2));

PerlScript example

$world->note ($world->GetPluginTimerInfo   ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2));

Python example

world.note(world.GetPluginTimerInfo   ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2))

VBscript example

world.note world.GetPluginTimerInfo ("c8efc9f9e1edd118c6f2dbf5", "my_timer", 2)

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 AddTimer (Adds a timer)

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 DeleteTimer (Deletes a timer)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginTimerInfo)


GetPluginTimerList

Script function

world.GetPluginTimerList

 Read about scripting

Type

Method

Summary

Gets the list of timers in a specified plugin

Prototype

VARIANT GetPluginTimerList(BSTR PluginID);

 View list of data type meanings

Description

Returns an array of all the named timers currently defined for the nominated plugin. You can then use GetPluginTimerInfo to find out more details about each one.

If you want to find the list of timers in the current plugin, use "GetTimerList".

If you are writing a plugin and want to find the "global" MUSHclient timer list, use an empty plugin ID, eg.

 tList = world.GetPluginTimerList ("")

Return value

If there are no timers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the timers in the specified plugin. Use "ubound" to find the number of timers in the list. You can then use "GetPluginTimerInfo" to find details about each timer.

Lua example

for k, v in pairs (GetPluginTimerList ("982581e59ab42844527eec80")) do

  Note (v)

end

Jscript example

timerlist = new VBArray(world.GetPluginTimerList("982581e59ab42844527eec80")).toArray();

if (timerlist)  // if not empty

 for (i = 0; i < timerlist.length; i++)

   world.note(timerlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetPluginTimerList ("982581e59ab42844527eec80")))

 {

 $world->note($item);

 }

Python example

timerlist = world.GetPluginTimerList("982581e59ab42844527eec80")

if (timerlist):

  for t in timerlist : world.Note (t)

VBscript example

dim tList

tList = world.GetPluginTimerList ("982581e59ab42844527eec80")

If Not IsEmpty (tList) Then

  for each t in tList

    world.note t

  next

End If

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 AddTimer (Adds a timer)

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 DeleteTimer (Deletes a timer)

 EnablePlugin (Enables or disables the specified plugin)

 EnableTimer (Enables or disables an timer)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 IsTimer (Tests to see if a timer exists)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginTimerList)


GetPluginTimerOption

Script function

world.GetPluginTimerOption

 Read about scripting

Type

Method

Summary

Gets the value of a named timer option for a specified plugin

Prototype

VARIANT GetPluginTimerOption(BSTR PluginID, BSTR TimerName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a timer option for the specified plugin.

You must specify a plugin ID, the name of an existing timer, and a timer option from the list given under the description for GetTimerOption. These are the same names as used in the XML world files for timer options.

If you want to find the value of an timer option in the current plugin, use "GetTimerOption".

If you are writing a plugin and want to find "global" MUSHclient timer values, use an empty plugin ID, eg.

  world.Note world.GetPluginTimerOption ("", "my_timer", "enabled")

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See GetTimerOption for a list of option names and values.

Return value

As described above.

Lua example

Note (GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

Note (GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"));

PerlScript example

/$world->Note ($world->GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"));

Python example

world.Note(world.GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"))

VBscript example

Note GetPluginTimerOption("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetPluginTimerOption)


GetPluginTriggerInfo

Script function

world.GetPluginTriggerInfo

 Read about scripting

Type

Method

Summary

Gets details about a named trigger for a specified plugin

Prototype

VARIANT GetPluginTriggerInfo(BSTR PluginID, BSTR TriggerName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified trigger for the specified plugin.

You can obtain various "types" of information about the trigger by specifying an "InfoType". The possible InfoTypes are described under GetTriggerInfo.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. If the plugin does not exist, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a trigger in the current plugin, use "GetTriggerInfo".

If you are writing a plugin and want to find "global" MUSHclient trigger values, use an empty plugin ID, eg.

  world.Note world.GetPluginTriggerInfo ("", "my_trigger", 1)

Return value

The specified information about the trigger, as described above.

An EMPTY variant, if the trigger does not exist.

A NULL variant if the trigger name is invalid.

A NULL variant if the InfoType is not a valid type.

A NULL variant if the plugin is not installed.

Lua example

Note (GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

/world.note(world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2));

PerlScript example

/$world->note ($world->GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2));

Python example

world.note(world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2))

VBscript example

world.note world.GetPluginTriggerInfo ("c8efc9f9e1edd118c6f2dbf5", "monster", 2)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetPluginTriggerInfo)


GetPluginTriggerList

Script function

world.GetPluginTriggerList

 Read about scripting

Type

Method

Summary

Gets the list of triggers in a specified plugin

Prototype

VARIANT GetPluginTriggerList(BSTR PluginID);

 View list of data type meanings

Description

Returns an array of all the named triggers currently defined for the nominated plugin. You can then use GetPluginTriggerInfo to find out more details about each one.

If you want to find the list of triggers in the current plugin, use "GetTriggerList".

If you are writing a plugin and want to find the "global" MUSHclient trigger list, use an empty plugin ID, eg.

 trList = world.GetPluginTriggerList ("")

Return value

If there are no triggers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the triggers in the specified plugin. Use "ubound" to find the number of triggers in the list. You can then use "GetPluginTrigger" to find details about each trigger.

Lua example

for k, v in pairs (GetPluginTriggerList ("982581e59ab42844527eec80")) do

  Note (v)

end

Jscript example

triggerlist = new VBArray(world.GetPluginTriggerList("982581e59ab42844527eec80")).toArray();

if (triggerlist)  // if not empty

 for (i = 0; i < triggerlist.length; i++)

   world.note(triggerlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetPluginTriggerList ("982581e59ab42844527eec80")))

 {

 $world->note($item);

 }

Python example

triggerlist = world.GetPluginTriggerList("982581e59ab42844527eec80")

if (triggerlist ):

  for t in triggerlist : world.Note (t)

VBscript example

dim trList

trList = world.GetPluginTriggerList ("982581e59ab42844527eec80")

If Not IsEmpty (trList) Then

  for each t in trList

    world.note t

  next

End If

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetPluginTriggerList)


GetPluginTriggerOption

Script function

world.GetPluginTriggerOption

 Read about scripting

Type

Method

Summary

Gets the value of a named trigger option for a specified plugin

Prototype

VARIANT GetPluginTriggerOption(BSTR PluginID, BSTR TriggerName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a trigger option for the specified plugin.

You must specify a plugin ID, the name of an existing trigger, and a trigger option from the list given under the description for GetTriggerOption. These are the same names as used in the XML world files for trigger options.

If you want to find the value of an trigger option in the current plugin, use "GetTriggerOption".

If you are writing a plugin and want to find "global" MUSHclient trigger values, use an empty plugin ID, eg.

  world.Note world.GetPluginTriggerOption ("", "my_trigger", "enabled")

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See GetTriggerOption for a list of option names and values.

Return value

As described above.

Lua example

Note (GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

Note (GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"));

PerlScript example

/$world->Note ($world->GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"));

Python example

world.Note(world.GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"))

VBscript example

Note GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 AddTrigger (Adds a trigger)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DeleteTrigger (Deletes a trigger)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetPluginTriggerOption)


GetPluginVariable

Script function

world.GetPluginVariable

 Read about scripting

Type

Method

Summary

Gets the contents of a variable belonging to a plugin

Prototype

VARIANT GetPluginVariable(BSTR PluginID, BSTR VariableName);

 View list of data type meanings

Description

Gets the contents of the named variable for the nominated plugin. Each plugin has a unique ID - specify that ID to identify the plugin in question.

If the named variable does not exist, EMPTY is returned.

If the name given is invalid, NULL is returned.

If the nominated plugin does not exist, NULL is returned.

(Use "IsEmpty" and "IsNull" to test for these possibilities).

If you want to find the value of a variable in the current plugin, use "GetVariable".

If you are writing a plugin and want to find a "global" MUSHclient variable value, use an empty plugin ID, eg.

  world.Note world.GetPluginVariable ("", "target")

Return value

The contents of the specified variable for the specified plugin.

An EMPTY variant, if the variable does not exist.

A NULL variant if the variable name is invalid, or the plugin is not installed.

Lua example

MyName = GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName")

if MyName == nil then

  Note("MyName is not defined")

else

  Note(MyName)

end

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

var MyName;

MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName");

if (MyName == null)

  world.note("MyName is not defined");

else

  world.note(MyName);

PerlScript example

$MyName = $world->GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName");

if (!defined ($MyName))

  {

  $world->note ("MyName is not defined");

  }

else

  {

  $world->note ($MyName);

  }

Python example

MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName")

if not MyName:

  world.note("MyName is not defined")

else:

  world.note(MyName)

VBscript example

dim MyName

MyName = world.GetPluginVariable ("a42fbf74f394d8129df956ae", "MyName")

if isempty (MyName) then

  world.note "My name is not defined"

end if

if isnull (MyName) then

  world.note "Invalid variable name"

end if

world.note MyName

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 SetVariable (Sets the value of a variable)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginVariable)


GetPluginVariableList

Script function

world.GetPluginVariableList

 Read about scripting

Type

Method

Summary

Gets the list of variables in a specified plugin

Prototype

VARIANT GetPluginVariableList(BSTR PluginID);

 View list of data type meanings

Description

Returns an array of all the variables currently defined for the nominated plugin. You can then use GetPluginVariable to get the value for each one.

If you want to find the list of variables in the current plugin, use "GetVariableList".

If you are writing a plugin and want to find the "global" MUSHclient variable list, use an empty plugin ID, eg.

 vList = world.GetPluginVariableList ("")

Return value

If there are no variables then the return value is empty. Use "IsEmpty" to test for this possibility.

If the nominated plugin does not exist, then the return value is NULL. Use "IsNull" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the variables in the specified plugin. Use "ubound" to find the number of variables in the list. You can then use "GetPluginVariable" to find details about each variable.

Lua example

-- show all variables and their values

for k, v in pairs (GetPluginVariableList("982581e59ab42844527eec80")) do

  Note (k, " = ", v)

end

Lua notes

Under Lua this function returns a table of all variables and their values,

keyed by the variable name.

Thus you can directly access variables from the table, like this:

-- show value for variable "victim" in plugin ID "982581e59ab42844527eec80" ...

print (GetPluginVariableList("982581e59ab42844527eec80").victim)

Jscript example

varList = new VBArray(world.GetPluginVariableList("982581e59ab42844527eec80")).toArray();

if (varList)  // if not empty

 for (i = 0; i < varList.length; i++)

   world.note(varList [i] + " = " +

         world.GetPluginVariable("982581e59ab42844527eec80", varList [i]));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetPluginVariableList ("982581e59ab42844527eec80")))

 {

 ($key, $value) = ($item, $world->GetPluginVariable ("982581e59ab42844527eec80", $item));

 $world->note($key . " = " . $value) if (defined ($key));

 }

Python example

variablelist = world.GetPluginVariableList("982581e59ab42844527eec80")

if (variablelist ):

  for v in variablelist : world.Note (v + " = " +

                  world.GetPluginVariable("982581e59ab42844527eec80", v))

VBscript example

dim varList

varList = world.GetPluginVariableList ("982581e59ab42844527eec80")

If Not IsEmpty (varList) Then

  For Each v In varList

    world.note v & " = " &  world.GetPluginVariable ("982581e59ab42844527eec80", v)

  Next

End If

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=GetPluginVariableList)


GetQueue

Script function

world.GetQueue

 Read about scripting

Type

Method

Summary

Returns a variant array which is a list of queued commands

Prototype

VARIANT GetQueue();

 View list of data type meanings

Description

Returns an array of the currently queued commands (speedwalks etc.).

You might use this if you needed to do something urgently. Retrieve the queue into an array, discard the queue, and then requeue it.

Return value

If there are no commands in the queue then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing all queued commands. Use "ubound" to find the number of commands in the list.

Lua example

for k, v in pairs (GetQueue()) do

  Note (v)

end

Jscript example

commandList = new VBArray(world.GetQueue()).toArray();

 if (commandList)

   for (i = 0; i < commandList.length; i++)

       world.note (commandList [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetQueue ()))

 {

 $world->note($item);

 }

Python example

commandList = world.GetQueue

if (commandList):

  for c in commandList : world.Note (c)

VBscript example

dim speedwalkQueue

  speedwalkQueue = world.GetQueue

  If Not IsEmpty (speedwalkQueue) Then

    For Each sw In speedwalkQueue

       world.note sw

    Next

  End If

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 DiscardQueue (Discards the speed walk queue)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 Queue (Queues a command for sending at the "speed walk" rate.)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetQueue)


GetReceivedBytes

Script function

world.GetReceivedBytes

 Read about scripting

Type

Method

Summary

Returns the number of bytes received from the world

Prototype

long GetReceivedBytes();

 View list of data type meanings

Description

Returns a count of the number of bytes received from the world.

The maximum number that can be returned by this function is a 31-bit number (ie. 0 to 2,147,483,647 bytes). This does not apply to Lua which returns the numbers as a "double" type (floating point).

If more bytes than that have been received the number will "wrap around" and become negative for a while.

Return value

The number of bytes received from the MUD.

Lua example

Note(GetReceivedBytes())

Lua notes

Lua will always return the correct number as the Lua data type is double, not long.

Jscript example

world.note(world.GetReceivedBytes());

PerlScript example

$world->note($world->GetReceivedBytes());

Python example

world.note(world.GetReceivedBytes)

VBscript example

world.note world.GetReceivedBytes

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetScriptTime (Returns the amount of time spent in script routines)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetReceivedBytes)


GetRecentLines

Script function

world.GetRecentLines

 Read about scripting

Type

Method

Summary

Assembles a block of text from recent MUD output

Prototype

BSTR GetRecentLines(long Count);

 View list of data type meanings

Description

This returns a block of text consisting of the nominated number of recently-arrived lines from the MUD.

It excludes notes or commands you type.

It includes lines even if they have been omitted from output by a trigger.

A "line" is a string of text from the MUD followed by a newline character. This is different from the lines returned by GetLineInfo which are physical lines which appear in the output window. Thus a line here might be shown as 5 lines on the screen if they wrapped around to fit them in.

The maximum number of lines stored by MUSHclient is the most recent 100. Thus, even if you request more than 100 lines you will only get 100.

The number you nominate is counted from the bottom, so if you ask for 1 line it will be the most recent, 2 lines will be the most recent 2 lines and so on.

Return value

A string containing the nominated number of lines of recent MUD output, separated by the newline character (hex 0A).

Lua example

Note (GetRecentLines (10))

VBscript example

world.Note GetRecentLines (10)

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetRecentLines)


GetScriptTime

Script function

world.GetScriptTime

 Read about scripting

Type

Method

Summary

Returns the amount of time spent in script routines

Prototype

double GetScriptTime();

 View list of data type meanings

Description

Returns the amount of time spent, in seconds compiling and executing scripts. This is a "double" type, which means that it can contain fractions of a second.

The current command (or script) is excluded from the time, as timing is done when the script routine finishes. Thus, if you type one of the examples below, and *then* check it against the figure shown in the MUSHclient scripting configuration page, they will disagree. However, if you check the time *first* and then run the example, then the times should agree to within 0.000001 seconds. The reason for that discrepancy is that the figure shown in the scripting configuration page is rounded to the 6th decimal place (ie. to the nearest microsecond).

Return value

The number of seconds, as a "double" spent executing scripts. The current script routine will not be counted, as it has not completed execution yet. Scripts which have errors are not counted in the time.

Lua example

Note(GetScriptTime())

Jscript example

world.note(world.getscripttime());

PerlScript example

$world->note($world->getscripttime());

Python example

world.note(world.getscripttime)

VBscript example

world.note world.getscripttime

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetLineCount (Gets count of lines received)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetSentBytes (Returns the number of bytes sent to the world)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GetScriptTime)


GetSelectionEndColumn

Script function

world.GetSelectionEndColumn

 Read about scripting

Type

Method

Summary

Returns the endling column of the selection in the output window

Prototype

long GetSelectionEndColumn();

 View list of data type meanings

Description

Returns the last column of the selected text in the output window (starting at 1).

If no selection, returns zero.

If you want to the current selection in the *command* window, use GetInfo(236) (first character) and GetInfo(237) (last character) instead.

Return value

The number of the last column in the selection, or zero if no selection.

The first column is 1.

Lua example

Note (GetSelectionEndColumn ())

Jscript example

world.note (world.GetSelectionEndColumn ());

PerlScript example

$world->note ($world->GetSelectionEndColumn ());

Python example

world.note (world.GetSelectionEndColumn )

VBscript example

world.note world.GetSelectionEndColumn

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSelectionEndColumn)


GetSelectionEndLine

Script function

world.GetSelectionEndLine

 Read about scripting

Type

Method

Summary

Returns the last line of the selection in the output window

Prototype

long GetSelectionEndLine();

 View list of data type meanings

Description

Returns a number in the range 1 to the number of lines in the output window, which is the last "selected" line.

If no selection, returns zero.

Return value

The number of the last line in the selection, or zero if no selection.

Lua example

Note (GetSelectionEndLine ())

Jscript example

world.note (world.GetSelectionEndLine ());

PerlScript example

$world->note ($world->GetSelectionEndLine ());

Python example

world.note (world.GetSelectionEndLine )

VBscript example

world.note world.GetSelectionEndLine

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSelectionEndLine)


GetSelectionStartColumn

Script function

world.GetSelectionStartColumn

 Read about scripting

Type

Method

Summary

Returns the starting column of the selection in the output window

Prototype

long GetSelectionStartColumn();

 View list of data type meanings

Description

Returns the first column of the selected text in the output window (starting at 1).

If no selection, returns zero.

If you want to the current selection in the *command* window, use GetInfo(236) (first character) and GetInfo(237) (last character) instead.

Return value

The number of the first column in the selection, or zero if no selection.

The first column is 1.

Lua example

Note (GetSelectionStartColumn ())

Jscript example

world.note (world.GetSelectionStartColumn ());

PerlScript example

$world->note ($world->GetSelectionStartColumn ());

Python example

world.note (world.GetSelectionStartColumn )

VBscript example

world.note world.GetSelectionStartColumn

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSelectionStartColumn)


GetSelectionStartLine

Script function

world.GetSelectionStartLine

 Read about scripting

Type

Method

Summary

Returns the starting line of the selection in the output window

Prototype

long GetSelectionStartLine();

 View list of data type meanings

Description

Returns a number in the range 1 to the number of lines in the output window, which is the first "selected" line.

If no selection, returns zero.

Return value

The number of the first line in the selection, or zero if no selection.

Lua example

Note (GetSelectionStartLine ())

Jscript example

world.note (world.GetSelectionStartLine ());

PerlScript example

$world->note ($world->GetSelectionStartLine ());

Python example

world.note (world.GetSelectionStartLine )

VBscript example

world.note world.GetSelectionStartLine

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSelectionStartLine)


GetSentBytes

Script function

world.GetSentBytes

 Read about scripting

Type

Method

Summary

Returns the number of bytes sent to the world

Prototype

long GetSentBytes();

 View list of data type meanings

Description

Returns a count of the number of bytes actually sent to the world. (This will exclude commands that are queued up that haven't yet been sent).

The maximum number that can be returned by this function is a 31-bit number (ie. 0 to 2,147,483,647 bytes). This does not apply to Lua which returns the numbers as a "double" type (floating point).

If more bytes than that have been sent the number will "wrap around" and become negative for a while.

Return value

The number of bytes sent to the MUD.

Lua example

Note(GetSentBytes())

Lua notes

Lua will always return the correct number as the Lua data type is double, not long.

Jscript example

world.note(world.GetSentBytes());

PerlScript example

$world->note($world->GetSentBytes());

Python example

world.note(world.GetSentBytes)

VBscript example

world.note world.GetSentBytes

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetScriptTime (Returns the amount of time spent in script routines)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSentBytes)


GetSoundStatus

Script function

world.GetSoundStatus

 Read about scripting

Type

Method

Summary

Gets the status of a sound started by PlaySound

Prototype

long GetSoundStatus(short Buffer);

 View list of data type meanings

Description

Gets the status of one of the sound buffers.

If you started playing a sound with StartSound this will tell you if it is still playing, and if so, whether it is set to loop or not.

Basically if the returned number is > 0 then the sound is playing, and if it is <= 0 then it is not playing.

You might test this in a timer to see if a sound had stopped playing (eg. some music), and if so, play something else.

Buffer: Which buffer to query (1 to 10).

Return value

-3: Sound system is not initialized (ie. DirectX not installed or too early version)

-2: That buffer is free (never played a sound, or the sound was stopped with StopSound)

-1: Requested buffer number out of range 1 to 10

 0: That buffer has reached the end and stopped playing

 1: That buffer is playing a sound, but not looping

 2: That buffer is playing a sound, which is a looping sound

Lua example

result = GetSoundStatus (1)

VBscript example

result = GetSoundStatus (1)  ' find what sound buffer 1 is doing

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GetSoundStatus)


GetStyleInfo

Script function

world.GetStyleInfo

 Read about scripting

Type

Method

Summary

Gets details about a specified style run for a specified line in the output window

Prototype

VARIANT GetStyleInfo(long LineNumber, long StyleNumber, short InfoType);

 View list of data type meanings

Description

Returns details about any style run for any line in the output buffer (window).

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window.

The style number can be from 1 (the first style on the line) to the number of styles in that line. You can use "world.GetLineInfo(LineNumber, 11)" to find the number of styles in each line.

You can obtain one of 15 "types" of information about the style by specifying an "InfoType". The possible InfoTypes are:

 1: text of style  (string)

 2: length of style run  (short)

 3: starting column of style  (short)

 4: action type - 0=none, 1=send to mud, 2=hyperlink, 3=prompt  (short)

 5: action   (eg. what to send)  (string)

 6: hint     (what to show)      (string)

 7: variable (variable to set)   (string)

 8: true if bold           (boolean)

 9: true if underlined     (boolean)

10: true if blinking       (boolean)

11: true if inverse        (boolean)

12: true if changed by trigger from original    (boolean)

13: true if start of a tag (action is tag name) (boolean)

14: foreground (text) colour in RGB   (long)

15: background colour in RGB          (long)

You could use this function to "reassemble" lines with ANSI codes or other markup, by putting appropriate codes around each style run. For instance, if the "bold" flag was set, you might use <b> ... </b> .

The "action type", "action", "hint" and "variable" fields are used by MXP. See the MXP write-ups on the MUSHclient forum for more detail about what they are used for.

The colour codes are in RGB - you could use NormalColour or BoldColour to work out which ANSI colour they corresponded to (note, they might not correspond to any ANSI colour if MXP, or world.note has been used to output non-standard colours).

Return value

The specified information about the style run, as described above.

An EMPTY variant, if the line or style does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

-- find foreground colour in RGB of style 2 on line 100

Note (GetStyleInfo (100, 2, 14))

-- display the text for style 2 on line 71

Note (GetStyleInfo (71) [2].text)

-- Same thing, done differently:

Note (GetStyleInfo (71, 2).text)

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

As an extension, you can supply zero for the StyleNumber and/or the InfoType.

If the StyleNumber is zero, then a table of all styles will be returned

(keyed numerically starting at one).

If the InfoType is omitted or zero, then all types of information

for the nominated style are returned in a table, keyed by type:

 text:       text of style (string)

 length:     length of style run (number)

 column:     starting column of style run (number)

 actiontype: action type - 0=none, 1=send to mud, 2=hyperlink, 3=prompt

 action:     action (eg. what to send) (string)

 hint:       hint (what to show) (string)

 variable:   variable (variable to set) (string)

 bold:       true if bold (boolean)

 ul:         true if underlined (boolean)

 blink:      true if blinking (boolean)

 inverse:    true if inverse (boolean)

 changed:    true if changed by trigger from original (boolean)

 starttag:   true if start of a tag (action is tag name) (boolean)

 textcolour: foreground (text) colour in RGB (number)

 backcolour: background colour in RGB (number)

This lets you readily re-assemble data from a particular line with only one

function call. Then just process the returned table.

If you omit (or set to zero) both the StyleNumber and InfoType then the

returned result will be a table of tables. The outer table will have one entry

per style, the inner table will have one entry per InfoType.

Example:

t = GetStyleInfo (71)     -- get all styles, all types for line 71

for k, v in pairs (t) do

  Note ("style run = ", k)  -- this is one style

  for a, b in pairs (v) do  -- display all info types for style

    Note (" item = ", a, " value = ", b)

  end

end

Jscript example

// find foreground colour in RGB of style 2 on line 100

world.note (world.GetStyleInfo (100, 2, 14));

PerlScript example

# find foreground colour in RGB of style 2 on line 100

$world->note ($world->GetStyleInfo (100, 2, 14));

Python example

# find foreground colour in RGB of style 2 on line 100

world.note (world.GetStyleInfo (100, 2, 14))

VBscript example

' find foreground colour in RGB of style 2 on line 100

world.note world.GetStyleInfo (100, 2, 14)

See Also ...

Topic

 Information

Functions

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetStyleInfo)


GetSysColor

Script function

world.GetSysColor

 Read about scripting

Type

Method

Summary

Gets the colour of various windows items

Prototype

long GetSysColor(long Index);

 View list of data type meanings

Description

This function directly calls GetSysColor in Windows. It returns the colour used by various items as currently configured in Windows, based on the selector (Index), as follows:

Scrollbar = 0

Background = 1

Active caption = 2

Inactive caption = 3

Menu = 4

Window = 5

Window frame = 6

Menu text = 7

Window text = 8

Caption text = 9

Active border = 10

Inactive border = 11

Application workspace = 12

Highlight = 13

Highlight text = 14

Button face = 15

Button shadow = 16

Gray text = 17

Button text = 18

Inactive caption text = 19

Button highlight = 20

3D dark shadow = 21

3D light = 22

Info text = 23

Info bk = 24

Return value

The RGB code corresponding to the selected colour index.

If the index is out of range, zero is returned.

Lua example

Note (RGBColourToName (GetSysColor (4)))  --> silver

Jscript example

Note (RGBColourToName (GetSysColor (4)))

VBscript example

Note RGBColourToName (GetSysColor (4))  ' --> may print "silver"

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSysColor)


GetSystemMetrics

Script function

world.GetSystemMetrics

 Read about scripting

Type

Method

Summary

Returns selected system information from Windows

Prototype

long GetSystemMetrics(long Index);

 View list of data type meanings

Description

The GetSystemMetrics function retrieves various system metrics (widths and heights of display elements) and system configuration settings. All dimensions retrieved by GetSystemMetrics are in pixels.

The information returned depends on the selector (Index), as follows:

CX screen = 0

CY screen = 1

CX vscroll = 2

CY hscroll = 3

CY caption = 4

CX border = 5

CY border = 6

CX dialog frame = 7

CY dialog frame = 8

CY v thumb = 9

CX h thumb = 10

CX icon = 11

CY icon = 12

CX cursor = 13

CY cursor = 14

CY menu = 15

CX full screen = 16

CY full screen = 17

CY kanji window = 18

Mouse present = 19

CY vscroll = 20

CX hscroll = 21

Debug = 22

Swap button = 23

Reserved1 = 24

Reserved2 = 25

Reserved3 = 26

Reserved4 = 27

CX min = 28

CY min = 29

CX size = 30

CY size = 31

CX frame = 32

CY frame = 33

CX min track = 34

CY min track = 35

CX double click = 36

CY double click = 37

CX icon spacing = 38

CY icon spacing = 39

Menu drop alignment = 40

Pen windows = 41

DBCS enabled = 42

Cmouse buttons = 43

Secure = 44

CX edge = 45

CY edge = 46

CX minspacing = 47

CY minspacing = 48

CX smicon = 49

CY smicon = 50

CY smcaption = 51

CX smsize = 52

CY smsize = 53

CX menusize = 54

CY menusize = 55

Arrange = 56

CX minimized = 57

CY minimized = 58

CX maxtrack = 59

CY maxtrack = 60

CX maximized = 61

CY maximized = 62

Network = 63

Clean boot = 67

CX drag = 68

CY drag = 69

Show sounds = 70

CX menucheck = 71

CY menucheck = 72

Slow machine = 73

Mid-east enabled = 74

Mouse wheel present = 75

X virtual screen = 76

Y virtual screen = 77

CX virtual screen = 78

CY virtual screen = 79

C monitors = 80

Same display format = 81

Return value

A number corresponding to the selected metric.

If the number is out of range, zero is returned.

Lua example

Note (GetSystemMetrics (0))   --> 1024

Note (GetSystemMetrics (1))   --> 768

Jscript example

Note (GetSystemMetrics (0))   //  --> 1024

Note (GetSystemMetrics (1))   //  --> 768

VBscript example

Note GetSystemMetrics (0)   '  --> 1024

Note GetSystemMetrics (1)   '  --> 768

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetSystemMetrics)


GetTimer

Script function

world.GetTimer

 Read about scripting

Type

Method

Summary

Gets details about a timer

Prototype

long GetTimer(BSTR TimerName, VARIANT* Hour, VARIANT* Minute, VARIANT* Second, VARIANT* ResponseText, VARIANT* Flags, VARIANT* ScriptName);

 View list of data type meanings

Description

Gets details about the specified timer name.

See AddTimer for a description of the meanings of the fields.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetTimerInfo instead. See below for how it works with Lua.

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerNotFound: The named timer does not exist

eOK: completed OK

 View list of return code meanings

Lua example

local status

local hour

local minute

local second

local response

local flags

local scriptname

status, hour, minute, second, response, flags, scriptname =

  GetTimer ("my_timer")

print (hour, minute, second, response, flags, scriptname)

Lua notes

Lua does not let you call by reference, however it can return multiple results.

Thus GetTimer is implemented to return the various fields as a multiple-return result,

as shown in the example above.

Jscript example

// Use GetTimerInfo when using Jscript

PerlScript example

# Use GetTimerInfo when using PerlScript

Python example

# Use GetTimerInfo when using Python

VBscript example

dim timername

dim timerhour

dim timerminute

dim timersecond

dim timerresponse

dim timerflags

dim timerscriptname

dim iStatus

iStatus = world.gettimer (timername, timerhour, timerminute, _

            timersecond, timerresponse, _

            timerflags, timerscriptname)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetTimer)


GetTimerInfo

Script function

world.GetTimerInfo

 Read about scripting

Type

Method

Summary

Gets details about a timer

Prototype

VARIANT GetTimerInfo(BSTR TimerName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified timer name.

You can obtain one of 26 "types" of information about the timer by specifying an "InfoType". The possible InfoTypes are:

 1: The hour (short)

 2: The minute (short)

 3: The second (short)

 4: What to send (string)

 5: Script procedure name (string)

 6: Enabled (boolean)

 7: One shot timer (boolean)

 8: "At" timer (if false, timer fires "every" hour/minute/second)  (boolean)

 9: Invocation count (long)

10: Times matched (long)

11: Date/time timer last fired (or was reset) (date)

12: Date/time timer will fire next (date)

13: Number of seconds until timer will fire next or zero if it is due to fire immediately (this might happen if the timer is due to fire but is disabled). (double)

14: 'temporary' flag (boolean)

15: 'speed walk' flag (boolean)

16: 'note' flag (boolean)

17: 'active when disconnected' flag (boolean)

18: Timer was included from an include file (boolean)

19: Group name (string)

20: Send-to location (long)

21: User option value (long)

22: Timer label (string)

23: 'Omit from output' flag (boolean)

24: 'Omit from log file' flag (boolean)

25: 'Executing-script' flag (boolean)

26: Script is valid flag (boolean)

The word in brackets indicates the "type" of data returned.

  String: a character string (eg. "north")

  Boolean: TRUE or FALSE

  Long: a 32-bit number

The field "invocation count" is a count of how many times the script routine was called.

The field "times matched" is a count of how many times the timer matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

The meanings of the "send-to" field are:

 0: World

 1: Command window

 2: Output window

 3: Status line

 4: Notepad (new)

 5: Notepad (append)

 6: Log File

 7: Notepad (replace)

 8: Command queue

 9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See AddTimer for a description of the meanings of the fields.

Return value

The specified information about the timer, as described above.

An EMPTY variant, if the timer does not exist.

A NULL variant if the timer name is invalid.

A NULL variant if the InfoType is not a valid type.

Lua example

Note(GetTimerInfo ("my_timer", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

world.note(world.GetTimerInfo ("my_timer", 2));

PerlScript example

$world->note ($world->GetTimerInfo ("my_timer", 2));

Python example

world.note(world.GetTimerInfo ("my_timer", 2))

VBscript example

world.note world.GetTimerInfo ("my_timer", 2)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetInfo (Gets information about the current world)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetTimerInfo)


GetTimerList

Script function

world.GetTimerList

 Read about scripting

Type

Method

Summary

Gets the list of timers

Prototype

VARIANT GetTimerList();

 View list of data type meanings

Description

Returns an array of all the named timers currently defined. You can then use GetTimer or GetTimerInfo for more details about each one.

Note - from version 3.40 onwards GetTimerList returns all timers, even unlabelled ones. The unlabelled timers will have assigned an "internal" label (like "*timer42") that can be used in GetTimerInfo, and similar routines.

Return value

If there are no timers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the timers. Use "ubound" to find the number of timers in the list.

Lua example

tl = GetTimerList ()

if tl then

  for k, v in ipairs (tl) do

    Note (v)

  end  -- for

end -- if we have any timers

Lua notes

Lua returns nil where applicable instead of an "empty variant".

Jscript example

timerlist = new VBArray(world.GetTimerList()).toArray();

if (timerlist)  // if not empty

 for (i = 0; i < timerlist.length; i++)

   world.note(timerlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetTimerList))

 {

 $world->note($item);

 }

Python example

timerlist = world.GetTimerList

if (timerlist):

  for t in timerlist : world.Note (t)

VBscript example

dim timerList

timerList = world.GetTimerList

If Not IsEmpty (timerList) then

   For Each t In timerList

     world.Note t

   next

End If

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetTimerList)


GetTimerOption

Script function

world.GetTimerOption

 Read about scripting

Type

Method

Summary

Gets the value of a named timer option

Prototype

VARIANT GetTimerOption(BSTR TimerName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a timer option.

You must specify the name of an existing timer, and a timer option from the list below. These are the same names as used in the XML world files for timer options.

Note that you can neither get nor set the "name" field. It is listed below for completeness in viewing timers copied to the clipboard or in world files and plugins. You already know the name when getting the timer option (it is TimerName), and this function is provided to modify existing timers, not rename them. To change the name of a timer use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddTimer.

If GetTimerOption is called from within a plugin, the timers for the current plugin are used, not the "global" MUSHclient timers.

To find options for timers in other plugins, use GetPluginTimerOption.

The various option names are:

"active_closed":            y/n - timer is active when world closed

"at_time":                  y/n - y=fire *at* time of day, otherwise every interval

"enabled":                  y/n - timer is enabled

"group":                    (string - group name)

"hour":                     hour to fire at (or every hour)

"minute":                   minute to fire at (or every minute)

"name":                     (string - name/label of alias)

"offset_hour":              offset hour - fire at time *plus* this

"offset_minute":            offset minute - fire at time *plus* this

"offset_second":            offset second - fire at time *plus* this

"omit_from_log":            y/n - omit timer from log file

"omit_from_output":         y/n - omit timer output from log file

"one_shot":                 y/n - delete after firing

"script":                   (string - name of function to call)

"second":                   hour to fire at (or every second)

"send":                     (multi-line string - what to send)

"send_to":                  0 - 13 - "send to" location (see below)

"user":                      -2147483647 to 2147483647 - user-defined number

"variable":                 (string - name of variable to send to)

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Return value

As described above.

Lua example

Note (GetTimerOption ("mytimer", "group"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

Note (world.GetTimerOption ("mytimer", "group"));

PerlScript example

$world->Note ($world->GetTimerOption ("mytimer", "group"));

Python example

world.Note (world.GetTimerOption ("mytimer", "group"))

VBscript example

Note world.GetTimerOption ("mytimer", "group")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=GetTimerOption)


GetTrigger

Script function

world.GetTrigger

 Read about scripting

Type

Method

Summary

Gets details about a named trigger

Prototype

long GetTrigger(BSTR TriggerName, VARIANT* MatchText, VARIANT* ResponseText, VARIANT* Flags, VARIANT* Colour, VARIANT* Wildcard, VARIANT* SoundFileName, VARIANT* ScriptName);

 View list of data type meanings

Description

Gets details about the specified trigger.

For a detailed description about the meanings of the fields, see AddTrigger.

This function does not appear to work when using Jscript or PerlScript, so if you are using those languages you should see GetTriggerInfo instead. See below for how it works with Lua.

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerNotFound: The named trigger does not exist

eOK: completed OK

 View list of return code meanings

Lua example

local status

local match

local response

local flags

local colour

local wildcard

local soundfilename

local scriptname

status, match, response, flags, colour, wildcard, soundfilename, scriptname =

 GetTrigger ("mytrigger")

print (match, response, flags, colour, wildcard, soundfilename, scriptname)

Lua notes

Lua does not let you call by reference, however it can return multiple results.

Thus GetTrigger is implemented to return the various fields as a multiple-return result,

as shown in the example above.

Jscript example

// Use GetTriggerInfo when using Jscript

PerlScript example

# Use GetTriggerInfo when using PerlScript

Python example

# Use GetTriggerInfo when using Python

VBscript example

dim trname

dim trmatch

dim trresponse

dim trflags

dim trcolour

dim trwildcard

dim trsoundfilename

dim trscriptname

dim iStatus

iStatus = world.gettrigger (trname, trmatch, trresponse,_

      trflags, trcolour, trwildcard, trsoundfilename, trscriptname)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetTrigger)


GetTriggerInfo

Script function

world.GetTriggerInfo

 Read about scripting

Type

Method

Summary

Gets details about a named trigger

Prototype

VARIANT GetTriggerInfo(BSTR TriggerName, short InfoType);

 View list of data type meanings

Description

Gets details about the specified trigger.

You can obtain one of 38 "types" of information about the trigger by specifying an "InfoType". The possible InfoTypes are:

 1: What to match on (string)

 2: What to send (string)

 3: Sound to play (string)

 4: Script procedure name (string)

 5: Omit from log (boolean)

 6: Omit from output (boolean)

 7: Keep evaluating (boolean)

 8: Enabled (boolean)

 9: Regular expression (boolean)

10: Ignore case (boolean)

11: Repeat on same line (boolean)

12: Play sound if inactive (boolean)

13: Expand variables (boolean)

14: Which wildcard to send to clipboard (short)

15: Send to - see below (short)

16: Sequence (short)

17: Match on (colour/style) (short)

18: Change to style (short)

19: Change to colour (short)

20: Invocation count (long)

21: Times matched (long)

22: Date/time trigger last matched (date)

23: 'temporary' flag (boolean)

24: Trigger was included from an include file (boolean)

25: Make wildcards lower case flag (boolean)

26: Group name (string)

27: Variable name (string)

28: User option value (long)

29: Other colour foreground colour value (long)

30: Other colour backgroundground colour value (long)

31: Number of matches to regular expression (most recent match) (long)

32: The string we matched against (last trigger text matched against) (string)

33: Executing-script flag (boolean)

34: Script is valid flag (boolean)

35: Error number from PCRE when evaluating last match (long), zero if none

36: 'one shot' flag (boolean)

37: Time taken (in seconds) to test triggers (including un-matched ones) (double)

38: Number of attempts to match this trigger (long)

101: Wildcard %1 from last time it matched

102: Wildcard %2 from last time it matched

103: Wildcard %3 from last time it matched

104: Wildcard %4 from last time it matched

105: Wildcard %5 from last time it matched

106: Wildcard %6 from last time it matched

107: Wildcard %7 from last time it matched

108: Wildcard %8 from last time it matched

109: Wildcard %9 from last time it matched

110: Wildcard %0 from last time it matched

Other wildcards can be extracted by using GetTriggerWildcard.

The word in brackets indicates the "type" of data returned.

  String: a character string (eg. "north")

  Boolean: TRUE or FALSE

  Short: a 16-bit number

  Long: a 32-bit number

The field "send to" indicates where the trigger response (item 2) gets sent:

 0: World

 1: Command window

 2: Output window

 3: Status line

 4: Notepad (new)

 5: Notepad (append)

 6: Log File

 7: Notepad (replace)

 8: Command queue

 9: Send To Variable

10: Execute (re-parse as command)

11: Speedwalk (send text is speedwalk, queue it)

12: Script (send to script engine)

13: Immediate (send to world in front of speedwalk queue)

14: Script - after omit (send to script engine, after omitting matching line from output)

The field "invocation count" is a count of how many times the script routine was called.

The field "times matched" is a count of how many times the trigger matched. These two would normally be the same, unless scripting was disabled, or there was an error in the script file.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the InfoType given is out of range, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddTrigger.

If GetTriggerInfo is called from within a plugin, the triggers for the current plugin are used, not the "global" MUSHclient triggers.

If you want to information about a trigger in another plugin, or the global MUSHclient triggers, use "GetPluginTriggInfo".

Return value

The specified information about the trigger, as described above.

An EMPTY variant, if the trigger does not exist.

A NULL variant if the trigger name is invalid.

A NULL variant if the InfoType is not a valid type.

Lua example

Note (GetTriggerInfo ("monster", 2))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

The "SendTo" field can be looked up using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

Jscript example

/world.note(world.gettriggerinfo ("monster", 2));

PerlScript example

/$world->note ($world->gettriggerinfo ("monster", 2));

Python example

world.note(world.gettriggerinfo ("monster", 2))

VBscript example

world.note world.gettriggerinfo ("monster", 2)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetInfo (Gets information about the current world)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetTriggerInfo)


GetTriggerList

Script function

world.GetTriggerList

 Read about scripting

Type

Method

Summary

Gets the list of triggers

Prototype

VARIANT GetTriggerList();

 View list of data type meanings

Description

Returns an array of all the named triggers currently defined. You can then use GetTrigger or GetTriggerInfo to find out more details about each one.

If GetTriggerList is called from within a plugin, the triggers for the current plugin are used, not the "global" MUSHclient triggers.

If you want to find the list of triggers in another plugin, or the global MUSHclient triggers, use "GetPluginTriggerList".

Note - from version 3.30 onwards GetTriggerList returns all triggers, even unlabelled ones. The unlabelled triggers will have assigned an "internal" label (like "*trigger42") that can be used in GetTriggerInfo, and similar routines.

Return value

If there are no triggers (with names) then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the triggers. Use "ubound" to find the number of triggers in the list. You can then use "GetTrigger" to find details about each trigger. See the example for how to do this. You can paste this example into an "Immediate" window (CTRL+I) to test it.

Lua example

tl = GetTriggerList()

if tl then

  for k, v in ipairs (tl) do

    Note (v)

  end  -- for

end -- if we have any triggers

Lua notes

Lua returns nil where applicable instead of an "empty variant".

Jscript example

triggerlist = new VBArray(world.GetTriggerList()).toArray();

if (triggerlist)  // if not empty

 for (i = 0; i < triggerlist.length; i++)

   world.note(triggerlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetTriggerList))

 {

 $world->note($item);

 }

Python example

triggerlist = world.GetTriggerList

if (triggerlist ):

  for t in triggerlist : world.Note (t)

VBscript example

dim trList

trList = world.GetTriggerList

If Not IsEmpty (trList) then

  For Each t In trList

    world.Note t

  Next

End If

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetTriggerList)


GetTriggerOption

Script function

world.GetTriggerOption

 Read about scripting

Type

Method

Summary

Gets the value of a named trigger option

Prototype

VARIANT GetTriggerOption(BSTR TriggerName, BSTR OptionName);

 View list of data type meanings

Description

Gets the current value of a trigger option.

You must specify the name of an existing trigger, and a trigger option from the list below. These are the same names as used in the XML world files for trigger options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing triggers copied to the clipboard or in world files and plugins. You already know the name when getting the trigger option (it is TriggerName), and this function is provided to modify existing triggers, not rename them. To change the name of a trigger use ExportXML, modify the XML, and then ImportXML.

The return type is Variant, so the returned value will be the appropriate type for the data (ie. string or number (long)).

If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

For a detailed description about the meanings of the fields, see AddTrigger.

If GetTriggerOption is called from within a plugin, the triggers for the current plugin are used, not the "global" MUSHclient triggers.

To find options for other plugins, use GetPluginTriggerOption.

The various option names are:

"clipboard_arg":             0 - 10 - which wildcard to copy to the clipboard

"colour_change_type":        0=both, 1=foreground, 2=background

"custom_colour":             0=no change, 1 - 16, 17=other

"enabled":                   y/n - trigger is enabled

"expand_variables":          y/n - expand variables (like @target)

"group":                     (string - group name)

"ignore_case":               y/n - caseless matching

"inverse":                   y/n - only match if inverse, however see match_inverse

"italic":                    y/n - only match if italic, however see match_italic

"keep_evaluating":           y/n - evaluate next trigger in sequence

"lines_to_match":            0 - 200 - how many lines to match for multi-line triggers

"lowercase_wildcard":        y/n - make matching wildcards lower-case

"match":                     (string - what to match)

"match_style":      (see below) - what style and colour combination to match on

"multi_line":                y/n - multi-line trigger

"name":                      (string - name/label of trigger)

"new_style":       (style(s) to change to: (bold (1) / underline (2) / italic (4) ) )

"omit_from_log":             y/n - omit matching line from log file

"omit_from_output":          y/n - omit matching line from output window

"one_shot":                  y/n - trigger is deleted after firing

"other_back_colour":         (string - name of colour to change to)

"other_text_colour":         (string - name of colour to change to)

"regexp":                    y/n - regular expression

"repeat":                    y/n - repeatedly evaluate on same line

"script":                    (string - name of function to call)

"send":                      (multi-line string - what to send)

"send_to":                   0 - 14 - "send to" location (see below)

"sequence":                  0 - 10000 - sequence in which to check - lower first

"sound":                     (string - sound file name to play)

"sound_if_inactive":         y/n - play sound even if world inactive

"user":                      -2147483647 to 2147483647 - user-defined number

"variable":                  (string - name of variable to send to)

Options that match on colour, bold, inverse or underline are tested against the first matching character.

Boolean options (shown as y/n) are returned as 0 for false (n) or 1 for true (y).

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Trigger match_style field will be as follows (in hex nibbles):

  TBFS

  T = what style to test

  B = background colour

  F = foreground colour

  S = what style bits are wanted

Style bits:

NORMAL     0x0000   // normal text

HILITE     0x0001   // bold

UNDERLINE  0x0002   // underline

BLINK      0x0004   // italic (sent to client as blink)

INVERSE    0x0008   // need to invert it

MATCH_TEXT      0x0080  // match on text colour?

MATCH_BACK      0x0800  // match on background colour?

MATCH_HILITE    0x1000  // match on bold bit?

MATCH_UNDERLINE 0x2000  // match on underline?

MATCH_BLINK     0x4000  // match on blink?

MATCH_INVERSE   0x8000  // match on inverse?

Colours:

BLACK = 0

RED = 1

GREEN = 2

YELLOW = 3

BLUE = 4

MAGENTA = 5

CYAN = 6

WHITE = 7

See the forum posting at http://www.gammon.com.au/forum/?id=4873 for more details about match_style.

Return value

As described above.

Lua example

Note (GetTriggerOption ("mytrigger", "match"))

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

Note (world.GetTriggerOption ("mytrigger", "match"));

PerlScript example

$world->Note ($world->GetTriggerOption ("mytrigger", "match"));

Python example

Note (world.GetTriggerOption ("mytrigger", "match"))

VBscript example

Note world.GetTriggerOption ("mytrigger", "match")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetTriggerOption)


GetTriggerWildcard

Script function

world.GetTriggerWildcard

 Read about scripting

Type

Method

Summary

Returns the contents of the specified wildcard for the named trigger

Prototype

VARIANT GetTriggerWildcard(BSTR TriggerName, BSTR WildcardName);

 View list of data type meanings

Description

Once a trigger has matched you can extract any of the wildcards for that trigger using this function.

The wildcards can be specified by name or number (if by number pass a string which is the appropriate number).

You can set up a named wildcard like this:

Match: (?P<who>.*) tells you '(?P<what>.*)'

In this case we have 2 wildcards, named "who" and "what".

Now we can extract wildcards like this:

x = GetTriggerWildcard ("mytrigger", "who")  ' get wildcard named 'who'

x = GetTriggerWildcard ("mytrigger", "what") ' get wildcard named 'what'

x = GetTriggerWildcard ("mytrigger", "22")   ' get wildcard 22 (if it exists)

You can have up to 999 wildcards, plus wildcard 0 which represents the entire matching string.

You can use GetTriggerInfo selector 31 to find how many wildcards matched.

Each wildcard will have a number and may optionally have a name.

Return value

The contents of the specified trigger wildcard, as described above.

An EMPTY variant, if the trigger does not exist.

A NULL variant if the trigger name is invalid.

An empty string if the wildcard does not exist. An empty string is the string "", this is different from an EMPTY variant.

Lua example

local x

x = GetTriggerWildcard ("mytrigger", "who")  -- get wildcard named 'who'

x = GetTriggerWildcard ("mytrigger", "what") -- get wildcard named 'what'

x = GetTriggerWildcard ("mytrigger", "22")   -- get wildcard 22 (if it exists)

Lua notes

Inside an trigger script function you can access named wildcards by

simply putting the name after the wildcards argument. eg.

function myTriggerFunction (name, line, wildcards)

  Note (wildcards.who)  --> access named wildcards "who"

end

VBscript example

dim x

x = GetTriggerWildcard ("mytrigger", "who")  ' get wildcard named 'who'

x = GetTriggerWildcard ("mytrigger", "what") ' get wildcard named 'what'

x = GetTriggerWildcard ("mytrigger", "22")   ' get wildcard 22 (if it exists)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=GetTriggerWildcard)


GetUdpPort

Script function

world.GetUdpPort

 Read about scripting

Type

Method

Summary

Find a free port for UDP listening

Prototype

long GetUdpPort(long First, long Last);

 View list of data type meanings

Description

This function finds a free port for use by MUSHclient as a UDP listener. It operates by scanning all open worlds for ports in use by UdpListen. It then works through the range you specify to find one that is not in use.

However this test is only for port used by MUSHclient. There is no guarantee that the port is not in use by another application.

The intention is for plugin writers to use it to find a port in a range (say, 4000 to 4100) which is not in use by another plugin, or the same plugin in another world.

The First and Last arguments are port numbers, inclusive, that you wish to be scanned. eg. GetUdpPort (4000, 4100) would find a port in the range 4000 to 4100 inclusive.

The port numbers must be greater than zero and less than 65535. Also the last port number must be greater than or equal to the first port number.

Return value

0 : No free port was found in the specified range, or the range was invalid.

non-zero : A port not in use by MUSHclient's UdpListen function.

Lua example

free_port = GetUdpPort (4000, 4100)

Jscript example

Note (GetUdpPort (4000, 4100))

VBscript example

Note GetUdpPort (4000, 4100)

See Also ...

Functions

 UdpListen (Listens for incoming packets using the UDP protocol)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 UdpSend (Sends a packet over the network using the UDP protocol)

(Help topic: function=GetUdpPort)


GetUniqueID

Script function

world.GetUniqueID

 Read about scripting

Type

Method

Summary

Creates a unique ID for general use, or for making Plugin IDs

Prototype

BSTR GetUniqueID();

 View list of data type meanings

Description

This uses CreateGUID to get a unique number, and then hashes it, retaining 24 characters (96 bits) of the hash. This generates a nice, unique identifier, like this: "0a96ce42d8e0ede554d3b9ab".

The advantage of using this over CreateGUID is that by hashing the number your network card MAC address is concealed. Conceivably some users might not want their MAC address to be revealed. The number generated here will be used by plugins to uniquely identify themselves.

You could also use it for variable, trigger, timer, alias names, when generated by a script, to ensure uniqueness over multiple sessions. You could also use it as a handy "password generator", as the number sequences are hardly going to be predicable.

Contrast this to "GetUniqueNumber" which only returns a unique number for this session of MUSHclient. Thus, the numbers (from "GetUniqueNumber") will not be unique over multiple sessions.

See also the new script function world.CreateGUID.

Also, using random number generation for unique identifiers has a chance of returning the same number, depending on a) the seed given to the generator; and b) the way the generator must eventually recyle and regenerate the same sequence.

Return value

A 24-character unique identifier.

Lua example

Note (GetUniqueID ())

Jscript example

world.Note (world.GetUniqueID ());

PerlScript example

$world->Note ($world->GetUniqueID ());

Python example

world.Note (world.GetUniqueID )

VBscript example

world.Note world.GetUniqueID

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GetUniqueID)


GetUniqueNumber

Script function

world.GetUniqueNumber

 Read about scripting

Type

Method

Summary

Returns a unique number

Prototype

long GetUniqueNumber();

 View list of data type meanings

Description

Returns a unique number in the range 0 to 2,147,483,647.

This number will be unique for this session of MUSHclient, across all worlds. You might use it to generate unique labels for one-shot timers, or other similar purposes.

Note that the number will eventually "wrap around" and thus, if you generate a lot of them (ie. 2,147,483,647 of them), they will no longer be unique.

Also note that this number generator is used internally in MUSHclient, and thus the numbers generated will not necessarily be in sequence.

Important - this number is reset for each new MUSHclient session, so these numbers are only unique per session, not indefinitely.

Return value

A unique number in the range 0 to 2147483647 as described above.

Lua example

Note (GetUniqueNumber())

Jscript example

world.note (world.GetUniqueNumber());

PerlScript example

$world->note ($world->GetUniqueNumber());

Python example

world.note (world.GetUniqueNumber)

VBscript example

world.note world.GetUniqueNumber

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=GetUniqueNumber)


GetVariable

Script function

world.GetVariable

 Read about scripting

Type

Method

Summary

Gets the contents of a variable

Prototype

VARIANT GetVariable(BSTR VariableName);

 View list of data type meanings

Description

Gets the contents of the named variable. If the named variable does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

If GetVariable is called from within a plugin, the variables for the current plugin are used, not the "global" MUSHclient variables.

If you want to find the value of a variable in another plugin, or the global MUSHclient variables, use "GetPluginVariable".

-----

RULES FOR NAMES

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

-----

SAVING AND LOADING

Please note that the following characters will not be handled correctly:

* The byte value hex 00 (otherwise known as 0x00 or null). This is used as a string terminator in MUSHclient, and attempts to imbed 0x00 values into variables will result in the variable being terminated at the 0x00 position.

* Carriage-return (hex 0D or 0x0D) and line-feeds (hex 0A or 0x0A). You can use these internally however you like, however when they are read from a plugin state file, or a MUSHclient world file, carriage returns are dropped, and line-feeds are converted to the sequence 0x0D 0x0A (carriage-return followed by linefeed). This is not normally a problem - because line breaks are usually stored as carriage-return/linefeed, and the reading process effectively will read them back in as that. However individual carriage-returns or linefeeds will not be read back in correctly.

If you are planning to use variables to store "binary" data - that is, data that can have all 256 possible character values, you are advised to convert them to base-64 encoded strings (using Base64Encode) when saving them, and conver them back (using Base64Decode) when loading them. Also be aware that only the Lua version of the base 64 encoding (utils.base64encode and utils.base64decode) will correctly handle the 0x00 value.

-----

RETRIEVING NUMBERS

Variables are stored as strings, so GetVariable returns a string, not a number. If the variable is supposed to be storing a numeric quantity (a count of mobs, hit points, or experience, for example) then you will probably need to convert it back to a number if it is going to be correctly processed inside a script. For example:

Lua:      x = tonumber (GetVariable ("x"))

JScript:  x = parseInt (GetVariable ("x"))

Python:   x = int (GetVariable ("x"))

VBscript: x = CInt (GetVariable ("x"))

These examples retrieve the variable "x" and use the "convert to number" function of the script language to convert it back into a script numeric variable.

Return value

The contents of the specified variable.

An EMPTY variant, if the variable does not exist.

A NULL variant if the variable name is invalid.

Lua example

local MyName

MyName = GetVariable("MyName")

if MyName == nil then

  Note ("MyName is not defined")

else

  Note (MyName)

end

Lua notes

Lua returns nil where applicable instead of an "empty variant" or "null variant".

Jscript example

var MyName;

MyName = world.GetVariable("MyName");

if (MyName == null)

  world.note("MyName is not defined");

else

  world.note(MyName);

PerlScript example

$MyName = $world->GetVariable("MyName");

if (!defined ($MyName))

  {

  $world->note ("MyName is not defined");

  }

else

  {

  $world->note ($MyName);

  }

Python example

MyName = world.GetVariable("MyName")

if not MyName:

  world.note("MyName is not defined")

else:

  world.note(MyName)

VBscript example

dim MyName

MyName = world.GetVariable ("MyName")

if isempty (MyName) then

  world.note "My name is not defined"

end if

if isnull (MyName) then

  world.note "Invalid variable name"

end if

world.note MyName

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 DeleteVariable (Deletes a variable)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 GetVariableList (Gets the list of variables)

 SetVariable (Sets the value of a variable)

(Help topic: function=GetVariable)


GetVariableList

Script function

world.GetVariableList

 Read about scripting

Type

Method

Summary

Gets the list of variables

Prototype

VARIANT GetVariableList();

 View list of data type meanings

Description

Returns an array of all the variables currently defined.

Return value

If there are no variables then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the variables. Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of variables in the list). You can then use "GetVariable" to find the contents of each variable.

Lua example

-- show all variables and their values

for k, v in pairs (GetVariableList()) do

  Note (k, " = ", v)

end

Lua notes

Under Lua this function returns a table of all variables and their values,

keyed by the variable name.

Thus you can directly access variables from the table, like this:

-- show value for variable "victim" ...

print (GetVariableList ().victim)

Jscript example

variablelist = new VBArray(world.GetVariableList()).toArray();

if (variablelist)  // if not empty

 for (i = 0; i < variablelist.length; i++)

   world.note(variablelist [i] + " = " +

       world.GetVariable(variablelist [i]));

PerlScript example

foreach $item (Win32::OLE::in ($world->GetVariableList))

 {

 ($key, $value) = ($item, $world->GetVariable ($item));

 $world->note($key . " = " . $value) if (defined ($key));

 }

Python example

variablelist = world.GetVariableList

if (variablelist ):

  for v in variablelist : world.Note (v + " = " +

                  world.GetVariable(v))

VBscript example

dim varList

varList = world.GetVariableList

If Not IsEmpty (varList) Then

  For Each v In varList

    world.note v & " = " &  world.GetVariable (v)

  Next

End If

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 SetVariable (Sets the value of a variable)

(Help topic: function=GetVariableList)


GetWorld

Script function

world.GetWorld

 Read about scripting

Type

Method

Summary

Gets an object reference to the named world

Prototype

IDispatch* GetWorld(BSTR WorldName);

 View list of data type meanings

Description

Returns an object which can be used to refer to another world.

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworld (name)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

You could use a small variation on the examples above to write your own "send to all worlds" or something similar.

If more than one world has the same name, only the first one matching that name will be returned. If this is likely, use GetWorldIDList to get a list of unique IDs (identifiers) and then use GetWorldById instead of GetWorld.

Return value

An object reference to the named world, if it was found.

Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.

In JavaScript use the test "== null" to see if the reference is to a valid world.

In PerlScript use the test "defined ()" to see if the reference is to a valid world.

In Python use the test "if (ref)" to see if the reference is to a valid world.

In Lua use the test "if ref == nil" to see if the reference is to a valid world.

Lua example

-- --------------------------------------------------

-- Example showing sending a message to another world

-- --------------------------------------------------

function SendToWorld (name, message)

local otherworld

  otherworld = GetWorld (name)

  if otherworld == nil then

    Note ("World " .. name .. " is not open")

    return

  end

  Send (otherworld, message)

  -- alternative syntax:   otherworld:Send (message)

end -- of SendToWorld

SendToWorld ("MyOtherWorld", "say Hi there")

Lua notes

Since Lua does not use the COM (Component Object Model) interface getting world

variables works differently than for other languages.

The function GetWorld returns a "userdata" item which contains the address of the other world.

You can pass this as the first argument to any MUSHclient function and that

function will then be applied to the target world.

eg.

otherworld = GetWorld ('pennmush')

Send (otherworld, "sigh")  --> send "sigh" to 'pennmush' world

An alternative syntax is to put the world name first, followed by a colon (not a dot),

like this:

otherworld:Send ("sigh")  --> send "sigh" to 'pennmush' world

Every function call that is passed a different world name is automatically checked to see

if the world is still open, so it is safe to use the world variable some time after

obtaining it (although an error will be raised if you do so).

You can protect function calls using pcall, so you might do this to see if the

world is still valid:

-- try to call WorldName for world 'otherworld'

ok = pcall (WorldName, otherworld)

if ok then

  Note "otherworld is OK"

else

  Note "otherword has closed"

end

Jscript example

// --------------------------------------------------

// Example showing sending a message to another world

// --------------------------------------------------

function SendToWorld (name, message)

{

 var otherworld

   otherworld = world.getworld (name);

  if (otherworld == null)

    {

    world.note("World " + name + " is not open");

    return;

    }

  otherworld.send(message);

}

SendToWorld ("MyOtherWorld", "say Hi there");

PerlScript example

# --------------------------------------------------

# Example showing sending a message to another world

# --------------------------------------------------

sub SendToWorld {

 my ($name, $message) = @_;

 my $otherworld;

 $otherworld = $world->getworld ($name);

  if (!defined ($otherworld))

    {

    $world->note("World " . $name . " is not open");

    return;

    }

  $otherworld->send($message);

}

SendToWorld ("MyOtherWorld", "say Hi there");

Python example

# --------------------------------------------------

# Example showing sending a message all worlds

# --------------------------------------------------

def SendToAllWorlds (message):

  worldlist = world.GetWorldList

  if (worldlist):

    for w in worldlist : world.GetWorld (w).Send (message)

SendToAllWorlds ("say Hi there")

VBscript example

' --------------------------------------------------

' Example showing sending a message to another world

' --------------------------------------------------

sub SendToWorld (name, message)

dim otherworld

  set otherworld = world.getworld (name)

  if otherworld is nothing then

    world.note "World " + name + " is not open"

    exit sub

  end if

  otherworld.send message

end sub

See Also ...

Topics

 Scripting

 World functions

Functions

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: function=GetWorld)


GetWorldById

Script function

world.GetWorldById

 Read about scripting

Type

Method

Summary

Gets an object reference to the world given its unique ID

Prototype

IDispatch* GetWorldById(BSTR WorldID);

 View list of data type meanings

Description

Returns an object which can be used to refer to another world.

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworldbyid (id)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

This does not apply to Lua which checks the world object every time it is used.

You could use a small variation on the examples above to write your own "send to all worlds" or something similar.

Return value

An object reference to the named world, if it was found.

Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.

In JavaScript use the test "== null" to see if the reference is to a valid world.

In PerlScript use the test "defined ()" to see if the reference is to a valid world.

In Lua use the test "if ref == nil" to see if the reference is to a valid world.

Lua example

-- --------------------------------------------------

-- Example showing sending a message all worlds

-- --------------------------------------------------

function SendToAllWorlds (message)

  for k, v in pairs (GetWorldIdList ()) do

    GetWorldById (v):Send (message)

  end

end

SendToAllWorlds ("say Hi there")

Lua notes

See the description for GetWorld for more discussion about using "world" variables in Lua.

Jscript example

// --------------------------------------------------

// Example showing sending a message all worlds

// --------------------------------------------------

function SendToAllWorlds (message)

{

 worldlist = new VBArray(GetWorldIdList()).toArray();

 if (worldlist)  // if not empty

  for (i = 0; i < worldlist.length; i++)

    GetWorldByID (worldlist [i]).Send (message);

}

SendToAllWorlds ("say Hi there");

PerlScript example

# --------------------------------------------------

# Example showing sending a message to another world

# --------------------------------------------------

sub SendToAllWorlds {

 my ($message) = @_;

 my $otherworld;

 foreach $item (Win32::OLE::in ($world->GetWorldIdList))

 {

 GetWorldById ($item)->Send ($message);

 }

}

SendToAllWorlds ("say Hi there");

Python example

# --------------------------------------------------

# Example showing sending a message all worlds

# --------------------------------------------------

def SendToAllWorlds (message):

  worldlist = world.GetWorldIdList

  if (worldlist):

    for w in worldlist : world.GetWorldByID (w).Send (message)

SendToAllWorlds ("say Hi there")

VBscript example

' --------------------------------------------------

' Example showing sending a message to all worlds

' --------------------------------------------------

sub SendToAllWorlds (message)

dim otherworld

for each id in GetWorldIdList

  set otherworld = GetWorldById (id)

  otherworld.Send message

  set otherworld = nothing

next

end sub

SendToAllWorlds "sigh"

See Also ...

Topics

 Scripting

 World functions

Functions

 GetWorld (Gets an object reference to the named world)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: function=GetWorldById)


GetWorldID

Script function

world.GetWorldID

 Read about scripting

Type

Method

Summary

Returns the 24-character ID of the current world

Prototype

BSTR GetWorldID();

 View list of data type meanings

Description

Returns the unique ID (identifier) of the currently-executing world.

Return value

The 24-character unique ID of the current world.

Lua example

Note ( GetWorldID ())

Jscript example

world.Note (world. GetWorldID ());

PerlScript example

$world->Note ($world-> GetWorldID ());

Python example

world.Note (world. GetWorldID )

VBscript example

world.Note world. GetWorldID

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetWorldID)


GetWorldIdList

Script function

world.GetWorldIdList

 Read about scripting

Type

Method

Summary

Gets the list of open worlds - returning their world IDs

Prototype

VARIANT GetWorldIdList();

 View list of data type meanings

Description

Returns a variant array which is a list of the identifiers (IDs) of all open worlds.

This is safer than using GetWorldList because multiple worlds might have the same name.

Return value

If there are no worlds then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the Ids of all the worlds. Use "ubound" to find the number of worlds in the list. You can then use "GetWorldById" to return a reference to that world.

Lua example

-- --------------------------------------------------

-- Example showing sending a message all worlds

-- --------------------------------------------------

function SendToAllWorlds (message)

  for k, v in pairs (GetWorldIdList ()) do

    GetWorldById (v):Send (message)

  end

end

SendToAllWorlds ("say Hi there")

Lua notes

See the description for GetWorld for more discussion about using "world" variables in Lua.

Jscript example

worldlist = new VBArray(world.GetworldIdList()).toArray();

if (worldlist)  // if not empty

 for (i = 0; i < worldlist.length; i++)

   Note (worldlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetWorldIdList))

 {

 Note ($item);

 }

Python example

worldlist = world.GetworldIdList

if (worldlist ):

  for w in worldlist : world.Note (w)

VBscript example

for each id in world.GetWorldIdList

  world.note id

next

See Also ...

Topics

 Scripting

 World functions

Functions

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldList (Gets the list of open worlds - returning their world names)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: function=GetWorldIdList)


GetWorldList

Script function

world.GetWorldList

 Read about scripting

Type

Method

Summary

Gets the list of open worlds - returning their world names

Prototype

VARIANT GetWorldList();

 View list of data type meanings

Description

Returns a variant array which is a list of all open worlds.

If more than one world has the same name you may get duplicates - to be able to refer to each world uniquely, use GetWorldIdList.

Return value

If there are no worlds then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the worlds. Use "ubound" to find the number of worlds in the list. You can then use "GetWorld" to return a reference to that world.

Lua example

for k, v in pairs (GetWorldList()) do

  Note (v)

end

Lua notes

See the description for GetWorld for more discussion about using "world" variables in Lua.

Jscript example

worldlist = new VBArray(world.GetworldList()).toArray();

if (worldlist)  // if not empty

 for (i = 0; i < worldlist.length; i++)

   world.note(worldlist [i]);

PerlScript example

foreach $item (Win32::OLE::in ($world->GetWorldList))

 {

 $world->note($item);

 }

Python example

worldlist = world.GetworldList

if (worldlist ):

  for w in worldlist : world.Note (w)

VBscript example

for each name in world.GetWorldList

  world.note name

next

See Also ...

Topics

 Scripting

 World functions

Functions

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 Open (Opens a named document)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: function=GetWorldList)


GetWorldWindowPosition

Script function

world.GetWorldWindowPosition

 Read about scripting

Type

Method

Summary

Returns the position and size of the current world window

Prototype

BSTR GetWorldWindowPosition();

 View list of data type meanings

Description

This function returns the size of the current world's window, in pixels.

For normal scripting languages these return a string, like this: "0,0,669,479". For Lua, see below.

To specify a window other than the first window either use Lua (see below) or the function GetWorldWindowPositionX.

Return value

Returns a string in the form:

left,top,width,height

eg. "0,0,669,479"

For Lua, returns a table containing:

top=(value)

height=(value)

left=(value)

width=(value)

Lua example

table.foreach (GetWorldWindowPosition(), print)

Lua notes

In Lua it returns a table with four entries, like this:

top 0

height 479

left 0

width 669

Lua has an optional argument which is the window number to examine. The first (main) window is window 1.

If you do Window -> New Window then you will get more windows, these will be 2, 3, 4 and so on.

You can use GetInfo (235) to find how many windows are currently open.

If you specify a window that does not exist you will get a nil result.

------------------

When using Lua the function GetWorldWindowPosition can take an optional second argument. If true, the world window position is reported in screen co-ordinates (that is, relative to the top-left corner of your monitor) rather than the default of relative to the main MUSHclient window. This lets you write plugins (like graphical status bars) that know where the world window is actually on the screen, so they can be drawn to be nearby.

------------------

When using Lua the function GetWorldWindowPosition can take an optional third argument. If true, a different method of calculating the window position is used (calling GetWindowRect rather than GetWindowPlacement). This method gives a more accurate result if you use "Aero Snap" under Windows 7 or higher. However it may return inaccurate results if the window is minimized.

eg.

GetMainWindowPosition (true)

The default is false, the original behaviour.

Also the top and left positions, when the third argument is true, are slightly different to those supplied when it is false, for reasons that are not completely obvious, but might be the height of the title bar and the width of the scroll bars.

Jscript example

Note (GetWorldWindowPosition ())

VBscript example

Note GetWorldWindowPosition

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 MoveWorldWindowX (Move and resize a specific world window)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetWorldWindowPosition)


GetWorldWindowPositionX

Script function

world.GetWorldWindowPositionX

 Read about scripting

Type

Method

Summary

Returns the position and size of a specific world window

Prototype

BSTR GetWorldWindowPositionX(short Which);

 View list of data type meanings

Description

This function returns the size of one of the current world's window, in pixels.

For normal scripting languages these return a string, like this: "0,0,669,479".

The first window is window number 1, the second one is 2, and so on. You create new windows by using Window menu -> New Window.

Return value

Returns a string in the form:

left,top,width,height

eg. "0,0,669,479"

Lua example

Not available in Lua - use GetWorldWindowPosition with a window number argument instead.

Lua notes

Lua has an optional argument to GetWorldWindowPosition which is the window number to get.

Jscript example

Note (GetWorldWindowPositionX (2))

VBscript example

Note GetWorldWindowPositionX (2)

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 MoveWorldWindowX (Move and resize a specific world window)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetWorldWindowPositionX)


GetXMLEntity

Script function

world.GetXMLEntity

 Read about scripting

Type

Method

Summary

Retrieves the value of a standard entity

Prototype

BSTR GetXMLEntity(BSTR Entity);

 View list of data type meanings

Description

Returns the value of a standard XML/MXP (HTML) entity.

To get user (server defined) entities use GetEntity.

Entity names are the standard HTML ones. There is a list on this page:

http://www.gammon.com.au/mushclient/mxpentities.htm

You can also use entities in the form: #nnn where nnn is a decimal number in the range 32 to 255.

You can also use entities in the form: #xhh where hh is a hexadecimal number in the range 20 to FF.

The entity name should *not* include the leading ampersand or trailing semicolon that you use in XML, MXP or HTML.

Return value

The contents of the specified entity, or an empty string if no such entity is found, or the syntax is invalid (eg. #999).

Lua example

Note (GetXMLEntity ("lt"))

Jscript example

world.Note (world.GetXMLEntity("lt"));

PerlScript example

$world->Note (world.GetXMLEntity("lt"));

Python example

world.Note (world.GetXMLEntity ("lt"))

VBscript example

world.Note world.GetXMLEntity("lt")

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetVariable (Gets the contents of a variable)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=GetXMLEntity)


Hash

Script function

world.Hash

 Read about scripting

Type

Method

Summary

Produces a hash (checksum) of a specified piece of text

Prototype

BSTR Hash(BSTR Text);

 View list of data type meanings

Description

This produces a 160-bit hash of the supplied text, returned as a 40-character hex string (40 X 4 bits = 160 bits). eg.

  world.note world.hash ("This Mud is running on the Dawn Codebase")

  c6a948fc8e81baa172a15aa534409b7654861a33

You might use this to store a hash of a long string (eg. a script file) to see if it has changed rather than storing the text itself.

There is no limit to the length of the string that can be hashed.

Because of the way strings are stored this will not work with strings which have nulls in them (hex 00), however see below for a work-around for Lua.

Return value

A 40-character hexadecimal string which is the hash of the supplied text.

Lua example

Note (Hash("This Mud is running on the Dawn Codebase"))

Lua notes

In MUSHclient version 3.57 onwards you can also use

hashed_string = utils.hash (s)

This works the same as described above, however it will correctly handle strings with the null (hex 00) character in them.

Jscript example

world.note (world.hash ("This Mud is running on the Dawn Codebase"));

PerlScript example

$world->note ($world->hash ("This Mud is running on the Dawn Codebase"));

Python example

world.note (world.hash ("This Mud is running on the Dawn Codebase"))

VBscript example

world.note world.hash ("This Mud is running on the Dawn Codebase")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=Hash)


Help

Script function

world.Help

 Read about scripting

Type

Method

Summary

Shows help for a script function, or a list of functions

Prototype

void Help(BSTR Name);

 View list of data type meanings

Description

This function is to help scripters quickly get information about script functions.

You can optionally supply a string argument. If the argument exactly matches a script function (case is not important) then the help for that function is shown.

eg.

/Help "colournote"  --> show help for world.ColourNote

If the argument partially matches a script function, then the "functions help" dialog box will be displayed with that text as the filter.

eg.

/Help "trigger"  --> show list of trigger-related functions

If the argument is empty then all script functions will be displayed.

The argument "lua" is a special case, and will show the help for all Lua-specific functions in MUSHclient.

eg.

/Help "lua"

You can also get help on Lua libraries by supplying "lua x" where x is the first letter of one of the standard Lua libraries, namely:

b - Base  (not in a library)

c - Coroutines

d - Debug

i - Io

m - Math

o - Os

p - Package

r - Rex

s - String

t - Table

u - Utils

You can type more letters if you want, but only the first 5 are checked. eg.

/Help "lua io"  --  (same as /Help "lua i")

In addition it also recognises:

/Help "lua bc" -- bc (bignum) library

Return value

Nothing.

Lua example

Help "colournote"

Help "lua io"

Lua notes

The argument is optional.

Jscript example

Help ("colournote")

VBscript example

Help "colournote"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=Help)


Hyperlink

Script function

world.Hyperlink

 Read about scripting

Type

Method

Summary

Creates a hyperlink in the output window

Prototype

void Hyperlink(BSTR Action, BSTR Text, BSTR Hint, BSTR TextColour, BSTR BackColour, BOOL URL);

 View list of data type meanings

Description

This lets you add a hyperlink to your output window (like a world.ColourTell). Because it is like a ColourTell you can precede or follow it by other text (by using ColourTell). Also, as it is like a ColourTell you should eventually wrap up the line with a Note or similar to "end the line".

You can specify:

* An action (what is done) - this is what gets sent. If URL is true it is sent to your web browser, otherwise it is sent to "Execute", that is the MUSHclient command processor.

  eg.  "north", "http://www.gammon.com.au/"

* Link text (what the player sees, underlined)

  eg. "go north", "Gammon Solutions web site"

* A hint (what appears if the mouse hovers over the hyperlink).

  If empty, defaults to the action.

  eg. "click to go north"

* A foreground colour

  The text colour. If empty, defaults to the note text colour.

  eg. "blue"

* A background colour. If empty, defaults to the note background colour.

  eg. "black"

* Whether it is a URL or not - if not, the action is executed like a command, otherwise it is sent to your web browser.

  If false, the action gets sent to the MUSHclient command parser, so it can be a simple command (eg. "eat food"), an alias (eg. "#chats"), a script (eg. '/world.note "hello" '), or a speedwalk.

  If true, the action must start with "http://", "https://", or "mailto:" and if so, it is sent to the web browser.

From version 3.42 you can also call a script in a plugin from a Hyperlink:

The hyperlink "action" text has a special case, that if it is in this format:

!!pluginID:sub(arg)

... then the sub "sub" in the plugin with that ID will be called, passing the argument "arg" (as a string).

For example:

world.Hyperlink "!!01245a24e83abd8552058478:nicktest(sigh)", "My test", "Click for my test", "yellow", "green", 0

In the example above we have:

Plugin ID = 01245a24e83abd8552058478

Sub to call = nicktest

Argument = sigh

Inside that plugin you might have a sub like this:

Sub nicktest (arg)

  Note arg

End Sub

Note that the brackets are required, so you would need: "sub()" if you wanted to pass no particular argument to the sub.

The argument will be passed as a string, so you don't need to quote it. It doesn't particularly matter if the argument contains brackets, as the processing of the argument simply starts at the first bracket, discards the last bracket, and sends everything inbetween (even if they are brackets).

For example:

world.Hyperlink "!!01245a24e83abd8552058478:nicktest(You say (hello))", "My test", "Click for my test", "yellow", "green", 0

The plugin is called using world.CallPlugin - see its description for more details.

Normally if you were using this inside a plugin, the plugin would find its own plugin ID, and then use that to generate the appropriate hyperlinks. eg. Inside a plugin you might do this:

world.Hyperlink "!!" & world.GetPluginID & ":mysub(North)", "Go North", "Click to go north", "yellow", "green", 0

... elsewhere in the plugin ...

Sub mysub (arg)

  Send arg

End Sub

------------------

WARNING!

Do not use the Hyperlink function in a script called by "sendto:script" from a trigger, if that trigger omits from output. The mechanism for preserving the "noted" output does not preserve hyperlinks. Use "sendto:script (after omit") instead.

Return value

Nothing.

Lua example

Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0)

Lua notes

Lua has a 7th optional argument: NoUnderline.

If true, the hyperlink is not underlined. It defaults to false.

Jscript example

Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0);

PerlScript example

Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0);

Python example

world.Hyperlink ("#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0)

VBscript example

world.Hyperlink "#chats", "Chat sessions", "Active chat sessions", "blue", "green", 0

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 CallPlugin (Calls a routine in a plugin)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=Hyperlink)


ImportXML

Script function

world.ImportXML

 Read about scripting

Type

Method

Summary

Imports configuration data in XML format

Prototype

long ImportXML(BSTR XML);

 View list of 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.

Return value

-1 : not XML format - failed initial check

-2 : error parsing XML - see error window

0 or more: count of items imported

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.

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>")

VBscript example

ImportXML _

  "<timers>" & _

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

  "</timer>" &_

  "</timers>"

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 &#x5C;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)

 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)


Info

Script function

world.Info

 Read about scripting

Type

Method

Summary

Adds text to the "info" tool bar

Prototype

void Info(BSTR Message);

 View list of data type meanings

Description

This adds the specified text to the info bar.

The bar is not cleared first, use InfoClear if you want to start a fresh lot of text.

If you want to change the colour, font or style of the text, use InfoFont and/or InfoColour before displaying the text.

The info bar may contain mixed colours, fonts and styles.

The info bar is shared between all worlds. Switching worlds will not change its contents.

Return value

Nothing.

Lua example

Info ("You are now connected")

Lua notes

You can supply multiple arguments, which are concatenated together.

eg.

Info ("You see ", themob, " here")

Jscript example

world.Info ("You are now connected");

PerlScript example

$world->Info ("You are now connected");

Python example

world.Info ("You are now connected")

VBscript example

world.Info "You are now connected"

See Also ...

Topic

 Info bar - programmable information bar

Functions

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 SetStatus (Sets the status line text)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: function=Info)


InfoBackground

Script function

world.InfoBackground

 Read about scripting

Type

Method

Summary

Sets the background colour for the info bar

Prototype

void InfoBackground(BSTR Name);

 View list of data type meanings

Description

Sets the backkground colour for the info bar. Because of the way the info bar is implemented (as a RichEdit control) the entire background colour is changed. You cannot change the background for individual parts of the bar.

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"

Return value

Nothing.

Lua example

InfoBackground ("red")

Jscript example

world.InfoBackground ("red");

PerlScript example

$world->InfoBackground ("red");

Python example

world.InfoBackground ("red")

VBscript example

world.InfoBackground "red"

See Also ...

Topic

 Info bar - programmable information bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 SetStatus (Sets the status line text)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: function=InfoBackground)


InfoClear

Script function

world.InfoClear

 Read about scripting

Type

Method

Summary

Clears all text from the info bar

Prototype

void InfoClear();

 View list of data type meanings

Description

Clears the info bar, ready to start adding new text to it.

The font and colour are restored to the defaults as well.

Return value

Nothing.

Lua example

InfoClear ()

Jscript example

world.InfoClear ();

PerlScript example

$world->InfoClear ();

Python example

world.InfoClear

VBscript example

world.InfoClear

See Also ...

Topic

 Info bar - programmable information bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 SetStatus (Sets the status line text)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: function=InfoClear)


InfoColour

Script function

world.InfoColour

 Read about scripting

Type

Method

Summary

Sets the colour of the foreground (text color) for the info bar

Prototype

void InfoColour(BSTR Name);

 View list of data type meanings

Description

Sets the text colour for subsequent text written to the info bar with world.Info.

The colours can either be named (eg. "red", "blue", "green", "brown") or supplied as HTML colour codes (eg. "#010203"). For HTML colours, the leading "#" is required.

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"

Return value

Nothing.

Lua example

InfoColour ("red")

Jscript example

world.InfoColour ("red");

PerlScript example

$world->InfoColour ("red");

Python example

world.InfoColour ("red")

VBscript example

world.InfoColour "red"

See Also ...

Topic

 Info bar - programmable information bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 SetStatus (Sets the status line text)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: function=InfoColour)


InfoFont

Script function

world.InfoFont

 Read about scripting

Type

Method

Summary

Changes the font, font size and style for text on the info bar

Prototype

void InfoFont(BSTR FontName, short Size, short Style);

 View list of data type meanings

Description

Changes the font, font size, and style of the next piece of text to be displayed on the info bar.

If the font name is empty, then the font is unchanged.

If the font size is zero, then the font size is unchanged. The font size is in points.

The style should be a combination of the numbers below (zero is just plain text). For instance, bold and italic would be 3.

Style bits:

    1 = bold

    2 = italic

    4 = underline

    8 = strikeout

eg. To display the next text in 12 point, FixedSys, bold, underline font:

world.InfoFont "FixedSys", 12, 5

Return value

Nothing.

Lua example

InfoFont ("FixedSys", 12, 5)

Info ("You are now connected")

Jscript example

world.InfoFont ("FixedSys", 12, 5);

world.Info ("You are now connected");

PerlScript example

$world->InfoFont ("FixedSys", 12, 5);

$world->Info ("You are now connected");

Python example

world.InfoFont ("FixedSys", 12, 5)

world.Info ("You are now connected")

VBscript example

world.InfoFont "FixedSys", 12, 5

world.Info "You are now connected"

See Also ...

Topic

 Info bar - programmable information bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 SetStatus (Sets the status line text)

 ShowInfoBar (Shows or hides the "info" tool bar)

(Help topic: function=InfoFont)


IsAlias

Script function

world.IsAlias

 Read about scripting

Type

Method

Summary

Tests to see if an alias exists

Prototype

long IsAlias(BSTR AliasName);

 View list of data type meanings

Description

Used to test if an alias exists.

Note that this function returns 0 if the alias *exists*.

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasNotFound: The named alias does not exist

eOK: completed OK - ie. The alias exists.

 View list of return code meanings

Lua example

Note(IsAlias("myalias"))

Jscript example

world.note(world.IsAlias("myalias"));

PerlScript example

$world->note($world->IsAlias("myalias"));

Python example

world.note(world.IsAlias("myalias"))

VBscript example

world.note world.IsAlias ("myalias")

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 SetAliasOption (Sets the value of a named alias option)

(Help topic: function=IsAlias)


IsConnected

Script function

world.IsConnected

 Read about scripting

Type

Method

Summary

Tests to see if the world is connected to the MUD server

Prototype

boolean IsConnected();

 View list of data type meanings

Description

This returns TRUE if the world is currently connected.

See GetInfo (227) for more details about the exact connection status.

There are actually a number of connection "phases" because connection is not synchronous. That is, connecting takes time.

If you are using a proxy server, with a username/password, there are 8 phases as described below. Not all phases are necessarily done, for example if the MUD address is already a "dotted decimal" number then a MUD name lookup is not required.

They are:

0=not connected (and not attempting to connect)

1=MUD name lookup (converting MUD name to an IP address)

2=Proxy server name lookup (converting proxy server name to an IP address)

3=connecting to MUD (establishing TCP/IP connection to the MUD)

4=connecting to proxy server (establishing TCP/IP connection to the proxy server)

5=proxy server phase 1 (sent SOCKS authentication method, awaiting confirmation)

6=proxy server phase 2 (sent SOCKS username/password, awaiting confirmation)

7=proxy server phase 3 (sent SOCKS connect details, awaiting confirmation)

8=connected to MUD (fully connected)

Strictly speaking, IsConnected returns true if the connection phase is 8 (connected to MUD) and false for any other phase.

Return value

TRUE if world connected

FALSE if not connected

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note(IsConnected())

Jscript example

world.note(world.IsConnected());

PerlScript example

$world->note($world->IsConnected());

Python example

world.note(world.IsConnected)

VBscript example

world.note world.IsConnected

See Also ...

Topic

 Information

Functions

 Connect (Connects the world to the MUD server)

 Debug (Displays debugging information about the world)

 Disconnect (Disconnects the world from the MUD server)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=IsConnected)


IsLogOpen

Script function

world.IsLogOpen

 Read about scripting

Type

Method

Summary

Tests to see if a log file is open

Prototype

boolean IsLogOpen();

 View list of data type meanings

Description

This returns true if the log file is currently open.

Return value

TRUE if world connected

FALSE if not connected

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note(IsLogOpen())

Jscript example

world.note(world.IsLogOpen());

PerlScript example

$world->note($world->IsLogOpen());

Python example

world.note(world.IsLogOpen)

VBscript example

world.note world.IsLogOpen

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=IsLogOpen)


IsPluginInstalled

Script function

world.IsPluginInstalled

 Read about scripting

Type

Method

Summary

Checks to see if a particular plugin is installed

Prototype

boolean IsPluginInstalled(BSTR PluginID);

 View list of data type meanings

Description

Use IsPluginInstalled to find if a particular plugin (identified by its unique Plugin ID) has been installed into this session of MUSHclient.

Return value

True if the plugin has been installed.

False if not installed.

Lua example

Note (IsPluginInstalled ("982581e59ab42844527eec80"))

Jscript example

world.note (world.IsPluginInstalled ("982581e59ab42844527eec80"));

PerlScript example

$world->note ($world->IsPluginInstalled ("982581e59ab42844527eec80"));

Python example

world.note (world.IsPluginInstalled ("982581e59ab42844527eec80"))

VBscript example

world.note world.IsPluginInstalled ("982581e59ab42844527eec80")

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=IsPluginInstalled)


IsTimer

Script function

world.IsTimer

 Read about scripting

Type

Method

Summary

Tests to see if a timer exists

Prototype

long IsTimer(BSTR TimerName);

 View list of data type meanings

Description

Used to test if a timer exists.

Note that this function returns 0 if the timer *exists*.

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerNotFound: The named timer does not exist

eOK: completed OK - ie. The timer exists.

 View list of return code meanings

Lua example

Note(IsTimer("mytimer"))

Jscript example

world.note(world.IsTimer("mytimer"));

PerlScript example

$world->note($world->IsTimer("mytimer"));

Python example

world.note(world.IsTimer("mytimer"))

VBscript example

world.note world.IsTimer ("mytimer")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=IsTimer)


IsTrigger

Script function

world.IsTrigger

 Read about scripting

Type

Method

Summary

Tests to see if a trigger exists

Prototype

long IsTrigger(BSTR TriggerName);

 View list of data type meanings

Description

Used to test if a trigger exists.

Note that this function returns 0 if the trigger *exists*.

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerNotFound: The named trigger does not exist

eOK: completed OK  (ie. The trigger exists)

 View list of return code meanings

Lua example

Note(IsTrigger("myTrigger"))

Jscript example

world.note(world.IsTrigger("myTrigger"));

PerlScript example

$world->note($world->IsTrigger("myTrigger"));

Python example

world.note(world.IsTrigger("myTrigger"))

VBscript example

world.note world.IsTrigger ("myTrigger")

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 SetTriggerOption (Sets the value of a named trigger option)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=IsTrigger)


LoadPlugin

Script function

world.LoadPlugin

 Read about scripting

Type

Method

Summary

Loads a plugin from disk

Prototype

long LoadPlugin(BSTR FileName);

 View list of data type meanings

Description

Loads a plugin file from disk. This is intended to let plugins load other plugins if desired. For example, you could make a "scan plugin directory" plugin, that loads all plugins found in a particular directory.

You might use "IsPluginInstalled" to see if a particular plugin is already installed.

If the plugin cannot be loaded an error window will open describing the problem with the plugin (eg. XML parsing error).

However if the problem is simply that the plugin file cannot be found, then no window will open.

You can use ReloadPlugin to reinstall a plugin once it is loaded, if you have changed it.

Return value

ePluginFileNotFound: Plugin file not found

eProblemsLoadingPlugin: Parsing or other problem in plugin file - see error window

eOK: Loaded OK

 View list of return code meanings

Lua example

LoadPlugin ("c:/mushclient/plugins/plugin_list.xml")

Jscript example

LoadPlugin ("c:/mushclient/plugins/plugin_list.xml");

PerlScript example

$world->LoadPlugin ("c:/mushclient/plugins/plugin_list.xml");

Python example

world.LoadPlugin ("c:/mushclient/plugins/plugin_list.xml")

VBscript example

LoadPlugin "c:/mushclient/plugins/plugin_list.xml"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=LoadPlugin)


LogInput

Script function

world.LogInput

 Read about scripting

Type

Property

Summary

The property of whether commands are logged to the log file

Prototype

short LogInput;

 View list of data type meanings

Description

Set to 1 to log commands to the log file, 0 to not log

Return value

This is a property. You can use it to find whether commands (your input) are currently logged.

Lua example

SetLogInput (true)   -- log input

SetLogInput (false)   -- don't log input

Note(GetLogInput ())  -- display whether input is logged

Lua notes

Lua implements this as two functions:

GetLogInput- gets whether input is logged

SetLogInput- sets whether input is logged

The argument is optional, and defaults to true.

Jscript example

world.loginput = 1;   // log input

world.loginput = 0;   // don't log input

world.note(world.loginput);  // display whether input is logged

PerlScript example

$world->{loginput} = 1;   # log input

$world->{loginput} = 0;   # don't log input

$world->note($world->{loginput});  # display whether input is logged

Python example

world.loginput = 1   # log input

world.loginput = 0   # don't log input

world.note(world.loginput)  # display whether input is logged

VBscript example

world.loginput = 1   ' log input

world.loginput = 0   ' don't log input

world.note world.loginput  ' display whether input is logged

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=LogInput)


LogNotes

Script function

world.LogNotes

 Read about scripting

Type

Property

Summary

The property of whether notes are logged to the log file

Prototype

short LogNotes;

 View list of data type meanings

Description

Set to 1 to log notes to the log file, 0 to not log

Return value

This is a property. You can use it to find whether notes are currently logged.

Lua example

SetLogNotes (true)   -- log notes

SetLogNotes (false)   -- don't log notes

Note(GetLogNotes ())  -- display whether notes are logged

Lua notes

Lua implements this as two functions:

GetLogNotes - gets whether notes are logged

SetLogNotes - sets whether notes are logged

The argument is optional, and defaults to true.

Jscript example

world.lognotes = 1;   // log notes

world.lognotes = 0;   // don't log notes

world.note(world.lognotes);  // display whether notes are logged

PerlScript example

$world->{lognotes} = 1;   # log notes

$world->{lognotes} = 0;   # don't log notes

$world->note($world->{lognotes});  # display whether notes are logged

Python example

world.lognotes = 1   # log notes

world.lognotes = 0   # don't log notes

world.note(world.lognotes)  # display whether notes are logged

VBscript example

world.lognotes = 1   ' log notes

world.lognotes = 0   ' don't log notes

world.note world.lognotes  ' display whether notes are logged

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=LogNotes)


LogOutput

Script function

world.LogOutput

 Read about scripting

Type

Property

Summary

The property of whether MUD output is logged to the log file

Prototype

short LogOutput;

 View list of data type meanings

Description

Set to 1 to log output to the log file, 0 to not log

Return value

This is a property. You can use it to find whether MUD output is currently logged.

Lua example

SetLogOutput (true)   -- log output

SetLogOutput (false)   -- don't log output

Note(GetLogOutput ())  -- display whether output is logged

Lua notes

Lua implements this as two functions:

GetLogOutput - gets whether output is logged

SetLogOutput - sets whether output is logged

The argument is optional, and defaults to true.

Jscript example

world.logoutput = 1;   // log output

world.logoutput = 0;   // don't log output

world.note(world.logoutput);  // display whether output is logged

PerlScript example

$world->{logoutput} = 1;   # log output

$world->{logoutput} = 0;   # don't log output

$world->note($world->{logoutput});  # display whether output is logged

Python example

world.logoutput = 1   # log output

world.logoutput = 0   # don't log output

world.note(world.logoutput)  # display whether output is logged

VBscript example

world.logoutput = 1   ' log output

world.logoutput = 0   ' don't log output

world.note world.logoutput  ' display whether output is logged

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

 WriteLog (Writes to the log file)

(Help topic: function=LogOutput)


LogSend

Script function

world.LogSend

 Read about scripting

Type

Method

Summary

Sends a message to the MUD and logs it

Prototype

long LogSend(BSTR Message);

 View list of data type meanings

Description

This sends the specified text to the world. It is like typing it into the command window.

The message text is also logged to the current log file, if one is open.

The data in the log file may not appear immediately if you view it in another application. To force the data to disk use the FlushLog function.

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

LogSend

[[

go north

eat food

drink water

]]

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.LogSend("go north");

PerlScript example

$world->LogSend("go north");

Python example

world.LogSend("go north")

VBscript example

world.logsend "go north"

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 Note (Sends a note to the output window)

 OpenLog (Opens a log file.)

 Send (Sends a message to the MUD)

 WriteLog (Writes to the log file)

(Help topic: function=LogSend)


MakeRegularExpression

Script function

world.MakeRegularExpression

 Read about scripting

Type

Method

Summary

Converts wildcard matching text to a regular expression

Prototype

BSTR MakeRegularExpression(BSTR Text);

 View list of data type meanings

Description

This function provides an interface to the internal routine that MUSHclient uses to convert trigger and alias "simple" wildcard expressions to full regular expressions. It is exactly the same result as provided by clicking on the "Convert to regular expression" button in the Edit Trigger dialog.

Example:

print (MakeRegularExpression ("* goes *"))

Output:

^(.*?) goes (.*?)$

The behaviour is basically:

* Put ^ at the start of the expression

* Put $ at the end of the expression

* Convert each occurrence of "*" to "(.*?)"

* Non-printable characters in the range 0x01 to 0x1F become hex sequences

* Non alphanumeric characters are escaped with a backslash.

Return value

The original string converted to a regular expression.

Lua example

Note (MakeRegularExpression ("* goes *"))

Jscript example

Note (MakeRegularExpression ("* goes *"))

VBscript example

Note MakeRegularExpression ("* goes *")

(Help topic: function=MakeRegularExpression)


MapColour

Script function

world.MapColour

 Read about scripting

Type

Method

Summary

Changes the colour mapping - the way colours are displayed

Prototype

void MapColour(long Original, long Replacement);

 View list of data type meanings

Description

You can specify a "map" of an original colour to the colour you want displayed.

The intention here is to let you override the colours sent down by MUDs, particularly using MXP colours, which are not subject to the normal ANSI colour palette.

For example, if a MUD annoys you by using a lot of red letters, you could do this:

MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))

The mapping is done at the last moment, in the output window display routine. The rest of MUSHclient will continue normally as if the colours had not changed.

You can map any number of colours, within reason. Potentially there are 16,777,216 different colours (2 to the power 24) however in practice a particular MUD is likely to only use a handful.

The colour must match *exactly* or the translation will not occur.

The arguments to the function are RGB colours (that is, numbers in the range 0 to 16,777,215) however you can use the function ColourNameToRGB as shown above if you want to use colour names.

The colour number is really made up of three bytes:

Red (low-order byte), ie. 0 to 255

Green (middle byte), ie. 0 to 255 multiplied by 256

Blue (higher-order byte), ie. 0 to 255 multiplied by 65536

To find the colour of a particular piece of text in the output window (so you can know the "from" colour) you can select it (eg. double-click) and then use the Display menu -> Text Attributes.

This will show you the Text and Background RGB colours (in HTML format). You can use those colours in the function ColourNameToRGB to translate them to numbers. eg.

x = ColourNameToRGB ("#FF00FF")

You can find the current mapping of a colour with GetMapColour, and a list of all mapped colours with MapColourList.

To make the new colours take effect immediately, call Redraw. This would only be necessary if you are changing colours "on the fly". If you are just customising colours at world startup this would not be necessary.

Return value

None.

Lua example

MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))

Jscript example

MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))

VBscript example

MapColour ColourNameToRGB ("red"), ColourNameToRGB ("green")

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 Redraw (Schedules a redraw for all windows for this world)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=MapColour)


MapColourList

Script function

world.MapColourList

 Read about scripting

Type

Method

Summary

Returns an array of all the mapped colours

Prototype

VARIANT MapColourList();

 View list of data type meanings

Description

Returns a variant array of all the colours that have been mapped for this world. eg.

black = red

blue = gold

Return value

If there are no colours mapped then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the source and destination colours with an " = " symbol between them.

However for Lua, it returns a table where the key is the original colour and the value is the replacement colour.

Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of colours in the list).

Lua example

-- show all colours and their values (RGB values)

for k, v in pairs (MapColourList()) do

  Note (k, " = ", v)

end

Lua notes

Under Lua this function returns a table of all mapped colours and their values,

keyed by the RGB colour code.

Thus you can directly access colours from the table, like this:

-- show value for colour 255...

print (MapColourList() [255])

Note that since this will return only colours in the table, if the colour doesn't exist in the mapping table, you will get nil from this example.

VBscript example

dim mapList

mapList= world.MapColourList

If Not IsEmpty (mapList) Then

  For Each v In mapList

    world.note v

  Next

End If

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=MapColourList)


Mapping

Script function

world.Mapping

 Read about scripting

Type

Property

Summary

A flag to indicate whether we are mapping the world

Prototype

boolean Mapping;

 View list of data type meanings

Description

This property controls whether automatic mapping takes place as you walk around.

Return value

TRUE if mapping is enabled

FALSE if mapping is NOT enabled

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note(GetMapping ())

SetMapping (false)

Lua notes

Lua implements this as two functions:

GetMapping - gets whether mapping occurs

SetMapping - sets whether mapping occurs

The argument is optional, and defaults to true.

Jscript example

world.note(world.Mapping);

PerlScript example

$world->note ($world->{Mapping});

Python example

world.note(world.Mapping)

VBscript example

world.note world.Mapping

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 RemoveMapReverses (A flag to indicate whether we backtracks are removed during mapping)

(Help topic: function=Mapping)


Menu

Script function

world.Menu

 Read about scripting

Type

Method

Summary

Creates a pop-up menu inside the command window

Prototype

BSTR Menu(BSTR Items, BSTR Default);

 View list of data type meanings

Description

This creates a pop-up menu inside the command window. This is intended to let you have context-sensitive items (or helpful reminders of MUD comamnds).

Items: A string containing the menu items to be displayed, see below.

Default: If provided, this item is selected.

The Items parameter is a string, containing the menu items to be displayed, separated by the "|" character. Leading and trailing spaces are removed from each item.

For example:  Item = "Take|Wield|Drop|Equip"

There must be at least one item,  or an empty string is returned.

The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned.

Return value

If there was an error condition as described above, the empty string.

If the menu was dismissed, or no item selected, the empty string.

Otherwise, the text of the selected item, with leading and trailing spaces removed.

Lua example

-- make Ctrl+F2 show various options, and paste into command window

AcceleratorTo ( "Ctrl+F2" ,

                'PasteCommand (Menu ("chat|yell|ask|say"))',

              sendto.script)

-- display all functions

result = Menu (table.concat (utils.functionlist ( ), "|" ))

Lua notes

The Default parameter is optional and defaults to the empty string (ie. no default).

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

(Help topic: function=Menu)


Metaphone

Script function

world.Metaphone

 Read about scripting

Type

Method

Summary

Returns the metaphone code for the supplied word

Prototype

BSTR Metaphone(BSTR Word, short Length);

 View list of data type meanings

Description

Returns a code indicating the "sound" of the supplied word. This is intended for use in a spell checker or similar to find words that sound the same or similar.

For example:

swordfish = SRTF,XRTF

Gammon = KMN

gamon = KMN

gamin = KMN

Cameron = KMRN

bruise = PRS

Bruce = PRS

You supply the word to be converted, and a length indicating the maximum size code you want returned.

This uses the "double metaphone" algorithm written by Lawrence Philips. It returns either a single metaphone (like KMN for Gammon) or two metaphones where an alternative pronunciation could be considered. Thus in the case of "swordfish" you could store that under SRTF or XRTF and consider both sound-alikes. If there is a comma present, then you know you had an alternative returned.

Because of this, if you specify a 4 character length, you might get back 9 characters (two 4-character metaphones, plus a comma).

Apart from the comma, only the following letters will be returned:

0 A F H J K L M N P R S T X

(First one is a zero indicating the "th" sound).

For a fast lookup, you could map each letter into a hex digit and then combine them into a single 16-bit number, eg.

0 = 0

A = 1

F = 2

H = 3

J = 4

K = 5

L = 6

M = 7

N = 8

P = 9

R = A

S = B

T = C

X = D

Return value

The converted code, or two codes separated by commas.

Lua example

Note (Metaphone ("swordfish"))

Lua notes

The length is optional and defaults to 4.

Also available as utils.metaphone.

VBscript example

Note Metaphone ("swordfish", 4)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 Menu (Creates a pop-up menu inside the command window)

 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)

 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)

 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=Metaphone)


MoveMainWindow

Script function

world.MoveMainWindow

 Read about scripting

Type

Method

Summary

Move and resize the main MUSHclient window

Prototype

void MoveMainWindow(long Left, long Top, long Width, long Height);

 View list of data type meanings

Description

This function moves and resizes the main MUSHclient window (the frame window inside which all world windows reside).

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

Return value

None.

Lua example

MoveMainWindow (1, 1, 640, 480)

Jscript example

MoveMainWindow (1, 1, 640, 480)

VBscript example

MoveMainWindow 1, 1, 640, 480

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 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)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 Menu (Creates a pop-up menu inside the command window)

 Metaphone (Returns the metaphone code for the supplied word)

 MoveNotepadWindow (Move and resize the specified notepad 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)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommandWindowHeight (Set the height of the command (input) window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 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=MoveMainWindow)


MoveNotepadWindow

Script function

world.MoveNotepadWindow

 Read about scripting

Type

Method

Summary

Move and resize the specified notepad window

Prototype

long MoveNotepadWindow(BSTR Title, long Left, long Top, long Width, long Height);

 View list of data type meanings

Description

This function moves and resizes the specified notepad's window.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

If the notepad window cannot be found, the function returns false (zero).

Return value

0: Could not do it (notepad window not found)

1:  Moved OK

Lua example

MoveNotepadWindow ("my_notepad", 1, 1, 640, 480))

Jscript example

MoveNotepadWindow ("my_notepad", 1, 1, 640, 480)

VBscript example

MoveNotepadWindow "my_notepad", 1, 1, 640, 480

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveWorldWindow (Move and resize a world window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

 SetToolBarPosition (Sets the position of the game toolbars on the screen.)

(Help topic: function=MoveNotepadWindow)


MoveWorldWindow

Script function

world.MoveWorldWindow

 Read about scripting

Type

Method

Summary

Move and resize a world window

Prototype

void MoveWorldWindow(long Left, long Top, long Width, long Height);

 View list of data type meanings

Description

This function moves and resizes the current world's window.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

To specify a window other than the first window either use Lua (see below) or the function MoveWorldWindowX.

Return value

None.

Lua example

MoveWorldWindow (1, 1, 640, 480, 2) -- move 2nd window

Lua notes

Lua has an optional 5th argument which is the window number to move. The first (main) window is window 1.

If you do Window -> New Window then you will get more windows, these will be 2, 3, 4 and so on.

You can use GetInfo (235) to find how many windows are currently open.

Jscript example

MoveWorldWindow (1, 1, 640, 480)

VBscript example

MoveWorldWindow 1, 1, 640, 480

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 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)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 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)

 MoveNotepadWindow (Move and resize the specified notepad 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)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommandWindowHeight (Set the height of the command (input) window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 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)

 SetWorldWindowStatus (Sets the scroll bar position, and hides or shows it)

 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=MoveWorldWindow)


MoveWorldWindowX

Script function

world.MoveWorldWindowX

 Read about scripting

Type

Method

Summary

Move and resize a specific world window

Prototype

void MoveWorldWindowX(long Left, long Top, long Width, long Height, short Which);

 View list of data type meanings

Description

This function moves and resizes one of the current world's windows.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

The first window is window number 1, the second one is 2, and so on. You create new windows by using Window menu -> New Window.

Return value

None.

Lua example

Not available in Lua - use MoveWorldWindow with a 5th argument instead.

Lua notes

Lua has an optional 5th argument to MoveWorldWindow which is the window number to move.

Jscript example

MoveWorldWindowX (1, 1, 640, 480, 2)

VBscript example

MoveWorldWindowX 1, 1, 640, 480, 2  ' move window 2

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 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)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 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)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a 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)

 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)

 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)

 SetWorldWindowStatus (Sets the scroll bar position, and hides or shows it)

 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=MoveWorldWindowX)


MtRand

Script function

world.MtRand

 Read about scripting

Type

Method

Summary

Returns pseudo-random number using the Mersenne Twister algorithm

Prototype

double MtRand();

 View list of data type meanings

Description

This returns a pseudo-random number in the range 0 to 1 (however excluding 1) as a "double" (floating-point number). Thus you can generate a number in any range by multiplying the result by the range you want.

eg.

print (math.floor (MtRand () * 5)) - returns 0 to 4

See below in the Lua section for an example of doing coin flips.

Note that the MT generator is "global" to all of MUSHclient. If you are trying to reproduce a sequence, then you cannot rely on a sequence staying stable from one script call to another (since another script, or another world or plugin, might also use random numbers).

This (Lua) script here, for example, would generate a million random numbers, and put them into a table for later use:

nums = {}  -- empty table

MtSrand (1234567) -- start with a known seed

for j = 1, 1000000 do

  table.insert (nums, MtRand ())

end

This took about a second to execute on my PC.

Over a run of 10,000,000 coins flips it seemed pretty accurate, giving 5,000,625 heads and 4,999,375 tails (in other words, around 50.00625% heads).

Example (in Lua) of rolling a 6-sided die:

for i = 1, 100 do

  Tell (math.floor (MtRand () * 6) + 1, " ")

end

In the above example, multiplying by 6 gives a number in the range 0 to 5, and then we add 1 to make it 1 to 6.

For more details about the Mersenne Twister see:

http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html

Return value

A pseudo-random number in the range [0 to 1). In other words, zero might be returned, however 1 will not be.

To put it another way, the returned number is:

>= 0 and < 1

Lua example

heads = 0

tails = 0

for j = 1, 1000000 do

  i = math.floor (MtRand () * 2)

  if i == 0 then

    heads = heads + 1

  else

    tails = tails + 1

  end  -- if

end  -- for

print ("heads = ", heads) --> 498893

print ("tails = ", tails) --> 501107

Jscript example

Note (MtRand ())

VBscript example

Note MtRand

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=MtRand)


MtSrand

Script function

world.MtSrand

 Read about scripting

Type

Method

Summary

Seed the Mersenne Twister pseudo-random number generator

Prototype

void MtSrand(long Seed);

 View list of data type meanings

Description

This seeds the MT generator with the given number, which is a 32-bit number.

Return value

Nothing.

Lua example

MtSrand (12345)

MtSrand { 88, 44, 95, 1234, 82343, 44853454 } -- see remarks below

Lua notes

You can also seed the Mersenne Twister with a table of seeds, rather than a single number.

This is because, although the MT generator has a period of 2^19937-1 (that is, the number of iterations before it repeats itself), the initial seeding is only a single number of 2^32 bits.

Thus there are effectively only 2^32 (4294967296) possible starting states for the generator.

However by initialising with an array of seeds you can effectively seed the generator to many different states.

The restrictions on using the array of seeds are:

* It only applies to Lua

* The seeds must be numbers (or convertible to numbers)

* There must be at least one number

* They must be an ordinary Lua vector-style table. That is, the key of the first seed is 1, the key of the second is 2, and so on.

* The seed numbers should be integers in the range 0 to 4294967296

Example:

t = { 1234, 5678, 9876, 5432 }

MtSrand (t) -- seed with table of seeds

MtSrand (8888) -- seed with single seed

The MT internal state consists of a vector of 624 32-bit numbers.

You can supply any size table, if it is less than 624 entries, effectively the ones you supply are repeated through the state table.

If you supply more they will be XOR'd with the earlier values. Probably 624 numbers is the maximum useful amount you can supply.

Jscript example

MtSrand (12345)

VBscript example

MtSrand 12345

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 PlaySound (Plays a sound using DirectSound)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 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)

 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=MtSrand)


NormalColour

Script function

world.NormalColour

 Read about scripting

Type

Property

Summary

Gets/sets the RGB colour for one of the 8 ANSI normal colours

Prototype

long NormalColour(short WhichColour);

void NormalColour(short WhichColour, long nNewValue);

 View list of data type meanings

Description

You can use this property to get or set the RGB colours used for the 8 ANSI normal colours. You must specify *which* colour you want to get/set, in the range 1 to 8, as follows:

black = 1

red     = 2

green   = 3

yellow  = 4

blue    = 5

magenta = 6

cyan    = 7

white   = 8

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

You should be cautious doing frequent colour changes, because what happens is that you are changing the *palette* colour. What this means in practice is that if you change (say) the white colour (colour 8) then when new text appears on the screen it will be drawn in the new colour, however existing text will stay the old colour *until* it is redrawn (eg. is covered by a dialog box). This may lead to patchy bits of different colour on the screen.

You can have different colours on the screen (at the same time) by using the 16 custom colours, but only 16 different colours can be visible at once.

You can force a redraw of the whole world's window(s) by using the "Redraw" method.

See also BoldColour.

Return value

This is a property. You can use it to find the current normal colour.

Lua example

Note (GetNormalColour (2))

SetNormalColour (2, 254)

Redraw()   -- redraw screen

Lua notes

Lua implements this as two functions:

GetNormalColour - gets the normal colour

SetNormalColour - sets the normal colour

Jscript example

world.note(world.normalcolour(3));

world.normalcolour (3) = 0xFF00;

world.normalcolour (8) = 0x303030;

world.redraw();  // redraw screen

PerlScript example

$world->Note($world->normalcolour(3));

$world->redraw   # redraw screen

Python example

world.note(world.normalcolour(3))

world.normalcolour (3) = 0xFF00

world.normalcolour (8) = 0x303030

world.redraw  # redraw screen

VBscript example

world.note world.normalcolour (3)

world.normalcolour (3) = vbGreen

world.normalcolour (8) = &h303030

world.redraw   ' redraw screen

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 Redraw (Schedules a redraw for all windows for this world)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=NormalColour)


Note

Script function

world.Note

 Read about scripting

Type

Method

Summary

Sends a note to the output window

Prototype

void Note(BSTR Message);

 View list of data type meanings

Description

This makes a note in the output window. It is not transmitted to the world. It is useful for making comments to yourself. The note is automatically terminated by a newline, so each world.Note will appear on a separate line.

The note appears in the current NoteColour (a custom colour), or in the RGB colours selected by NoteColourFore and NoteColourBack.

You can also choose colours with NoteColourRGB and NoteColourName.

If you want to change colours in the middle of a note, use Tell instead.

To make changes to the text style (eg. bold, underline) see NoteStyle.

Return value

Nothing.

Lua example

Note ("This monster is worth avoiding!")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.note("This monster is worth avoiding!");

PerlScript example

$world->note("This monster is worth avoiding!");

Python example

world.note("This monster is worth avoiding!")

VBscript example

world.note "This monster is worth avoiding!"

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 Send (Sends a message to the MUD)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=Note)


NoteColour

Script function

world.NoteColour

 Read about scripting

Type

Property

Summary

Chooses which custom colour will be used for world notes.

Prototype

short NoteColour;

 View list of data type meanings

Description

You can get or set this to change the colour (number) that the *next* world.note will be displayed in. The valid range is 0 to 16, where 0 is "no change", 1 is custom colour 1, through to 16 for custom colour 16.

If notes are currently being displayed in RGB mode (using NoteColourFore or NoteColourBack) then getting the NoteColour will return -1.

If notes are currently being displayed in RGB mode (using NoteColourFore or NoteColourBack) then setting the NoteColour will switch back to palette mode (the default).

It may be easier to use ColourNote to display notes in a different colour (in a single function) rather than changing the note colour and then doing a Note.

Return value

This is a property. You can use it to find the current note colour.

Lua example

Note (GetNoteColour ())

SetNoteColour (15) -- use custom colour 15

Lua notes

Lua implements this as two functions:

GetNoteColour - gets the note colour

SetNoteColour - sets the note colour

Jscript example

world.notecolour = 15;  // set note colour to use custom colour 15

world.note("This will be in custom colour 15");

world.note(world.notecolour);  // display current note colour

PerlScript example

$world->{notecolour} = 15;  # set note colour to use custom colour 15

$world->note("This will be in custom colour 15");

$world->note($world->{notecolour});  # display current note colour

Python example

world.notecolour = 15  # set note colour to use custom colour 15

world.note("This will be in custom colour 15")

world.note(world.notecolour)  # display current note colour

VBscript example

world.notecolour = 15  ' set note colour to use custom colour 15

world.note "This will be in custom colour 15"

world.note world.notecolour  ' display current note colour

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteStyle (Sets the style for notes)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteColour)


NoteColourBack

Script function

world.NoteColourBack

 Read about scripting

Type

Property

Summary

Chooses which RGB colour will be used for world notes - background colour

Prototype

long NoteColourBack;

 View list of data type meanings

Description

You can use this to set the background colour used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

Return value

This is a property. You can use it to find the current note background colour.

Lua example

SetNoteColourBack (255)  -- set note colour to use red background

Note ("This will be on a red background")

Note(GetNoteColourBack ())  -- display current note background colour

Lua notes

Lua implements this as two functions:

GetNoteColourBack - gets the note colour background

SetNoteColourBack - sets the note colour background

Jscript example

world.notecolourback = 0xFF;  // set note colour to use red background

world.note("This will be on a red background");

world.note(world.notecolourback);  // display current note background colour

PerlScript example

$world->{notecolourback} = 0xFF;  # set note colour to use red background

$world->note("This will be on a red background");

$world->note($world->{notecolourback});  # display current note background colour

Python example

world.notecolourback = 0xFF  # set note colour to use red background

world.note("This will be on a red background")

world.note(world.notecolourback)  # display current note background colour

VBscript example

world.notecolourback = vbRed  ' set note background colour to red

world.note "This will be on a red background"

world.note world.notecolourback  ' display current note background colour

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteColourBack)


NoteColourFore

Script function

world.NoteColourFore

 Read about scripting

Type

Property

Summary

Chooses which RGB colour will be used for world notes - text colour

Prototype

long NoteColourFore;

 View list of data type meanings

Description

You can use this to set the foreground (text) colour used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

If you are setting the colour you must specify an RGB value. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

Return value

This is a property. You can use it to find the current note text colour.

Lua example

SetNoteColourFore (255)  -- set note colour to use red foreground

Note ("This will be in red")

Note(GetNoteColourFore ())  -- display current note background colour

Lua notes

Lua implements this as two functions:

GetNoteColourFore - gets the note colour foreground

SetNoteColourFore - sets the note colour foreground

Jscript example

world.notecolourfore = 0xFF;  // set note colour to use red

world.note("This will be in red");

world.note(world.notecolourfore);  // display current note colour

PerlScript example

$world->{notecolourfore} = 0xFF;  # set note colour to use red

$world->note("This will be in red");

$world->note($world->{notecolourfore});  # display current note colour

Python example

world.notecolourfore = 0xFF  # set note colour to use red

world.note("This will be in red")

world.note(world.notecolourfore)  # display current note colour

VBscript example

world.notecolourfore = vbRed  ' set note colour to red

world.note "This will be in red"

world.note world.notecolourfore  ' display current note colour

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteColourFore)


NoteColourName

Script function

world.NoteColourName

 Read about scripting

Type

Method

Summary

Chooses which RGB colour name will be used for world notes - text and background

Prototype

void NoteColourName(BSTR Foreground, BSTR Background);

 View list of data type meanings

Description

You can use this to set the foreground (text) and background colours used in world.note and world.tell. The colour is specified as a colour name, eg. "red", "green", "beige", "cyan" and so on.

The names are not case-sensitive.

You can also use HTML colour codes, eg. "#7FFF00", in this case the colours are in the order #rrggbb (rr = red, gg = green, bb = blue).

If a particular colour is invalid or not found, then that colour will be unchanged. Thus you can use this function to change the foreground colour only, the background colour only, or both.

Eg.

world.notecolourname "red", ""  ' foreground only

world.notecolourname "", "blue"  ' background only

world.notecolourname "green", "cyan"  ' both

You can use MUSHclient's "colour picker" to choose a suitable name. Use the Edit menu -> Colour Picker to do this, or press Ctrl+Alt+P.

Return value

Nothing.

Lua example

NoteColourName ("red", "green")  -- set note colour to use red on green

Note("This will be in red on green")

Jscript example

world.notecolourname ("red", "green");  // set note colour to use red on green

world.note("This will be in red on green");

PerlScript example

$world->NoteColourname ("red", "green");  # set note colour to use red on green

$world->note("This will be in red on green");

Python example

world.notecolourname ("red", "green")  # set note colour to use red on green

world.note("This will be in red on green")

VBscript example

world.notecolourname "red", "green"  ' set note colour to red on green

world.note "This will be in red on green"

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteColourName)


NoteColourRGB

Script function

world.NoteColourRGB

 Read about scripting

Type

Method

Summary

Chooses which RGB colour will be used for world notes - text and background

Prototype

void NoteColourRGB(long Foreground, long Background);

 View list of data type meanings

Description

You can use this to set the foreground (text) and background colours used in world.note and world.tell. The colour is specified in RGB (Red, Green, Blue). Red is in the low-order byte, Green in the middle-order byte, and Blue in the higher-order byte. (ie. 0x00BBGGRR).

You must specify an RGB values. Some pre-defined values are available in VBscript, see below.

Constant   Value    Description

-------------------------------

vbBlack    &h00     Black

vbRed      &hFF     Red

vbGreen    &hFF00   Green

vbYellow   &hFFFF   Yellow

vbBlue     &hFF0000 Blue

vbMagenta  &hFF00FF Magenta

vbCyan     &hFFFF00 Cyan

vbWhite    &hFFFFFF White

In JScript and PerlScript you will need to use the RGB values, for example Magenta would be: 0xFF00FF.

To calculate this mathematically this would be:

colour = red + (green * 256) + (blue * 65536)

Return value

Nothing.

Lua example

NoteColourRGB (255, 256 * 255)  -- set note colour to use red on green

Note("This will be in red on green")

Jscript example

world.notecolourRGB (0xFF, 0xFF00);  // set note colour to use red on green

world.note("This will be in red on green");

PerlScript example

$world->NoteColourRGB (0xFF, 0xFF00);  # set note colour to use red on green

$world->note("This will be in red on green");

Python example

world.notecolourRGB (0xFF, 0xFF00)  # set note colour to use red on green

world.note("This will be in red on green")

VBscript example

world.notecolourRGB vbRed, vbGreen  ' set note colour to red on green

world.note "This will be in red on green"

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteColourRGB)


NoteHr

Script function

world.NoteHr

 Read about scripting

Type

Method

Summary

Draws a horizontal rule in the output window

Prototype

void NoteHr();

 View list of data type meanings

Description

This draws a horizontal rule in the output window, the same as is done by the MXP <hr> sequence.

Return value

Nothing.

Lua example

NoteHr ()

Jscript example

world.NoteHr();

PerlScript example

$world->NoteHr();

Python example

world.NoteHr()

VBscript example

world.NoteHr

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteStyle (Sets the style for notes)

 Send (Sends a message to the MUD)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteHr)


NotepadColour

Script function

world.NotepadColour

 Read about scripting

Type

Method

Summary

Changes the text and background colour of the selected notepad window

Prototype

long NotepadColour(BSTR Title, BSTR TextColour, BSTR BackgroundColour);

 View list of data type meanings

Description

This lets you set the text and background colour of an open notepad window.

eg.

AppendToNotepad ("test", "but does it get goat's blood out?") -- create window

NotepadColour ("test", "whitesmoke", "saddlebrown") -- change its colour

The colours are specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug ("colours").

You can also specify colours in HTML format, like this:

NotepadColour ("test", "#FAEBD7", "#FFB6C1")

Return value

0 = Could not do it (eg. that notepad does not exist, one of those colours do not exist)

1 = Colours changed OK.

Lua example

NotepadColour ("test", "#FAEBD7", "#FFB6C1")

NotepadColour ("test", "whitesmoke", "saddlebrown")

Jscript example

NotepadColour ("test", "#FAEBD7", "#FFB6C1");

NotepadColour ("test", "whitesmoke", "saddlebrown");

VBscript example

NotepadColour "test", "#FAEBD7", "#FFB6C1"

NotepadColour "test", "whitesmoke", "saddlebrown"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=NotepadColour)


NotepadFont

Script function

world.NotepadFont

 Read about scripting

Type

Method

Summary

Changes the font and style of the selected notepad window

Prototype

long NotepadFont(BSTR Title, BSTR FontName, short Size, short Style, short Charset);

 View list of data type meanings

Description

This lets you change the font, font size, style, and character set of the font for an open notepad window.

eg.

NotepadFont ("test", "Comic Sans MS", 11, 0, 0)

The arguments are:

notepad name

font name

font size

style bits

character set

If the font name is empty, then the font is unchanged.

If the font size is zero, then the font size is unchanged. The font size is in points.

The style should be a combination of the numbers below (zero is just plain text). For instance, bold and italic would be 3.

Style bits:

1 = bold

2 = italic

4 = underline

8 = strikeout

Return value

0 = Could not do it (eg. that notepad does not exist)

1 = Font and style changed OK.

Lua example

NotepadFont ("test", "Comic Sans MS", 11, 0, 0)

Lua notes

The charset argument is optional and defaults to zero.

Jscript example

NotepadFont ("test", "Comic Sans MS", 11, 0, 0);

VBscript example

NotepadFont "test", "Comic Sans MS", 11, 0, 0

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=NotepadFont)


NotepadReadOnly

Script function

world.NotepadReadOnly

 Read about scripting

Type

Method

Summary

Make a selected notepad window read-only

Prototype

long NotepadReadOnly(BSTR Title, BOOL ReadOnly);

 View list of data type meanings

Description

This lets you mark a notepad window as read-only.

This might be useful for help screens or other "output-only" information.

You can specify true or false as the second argument. Under Lua, it defaults to true.

Return value

0 = Could not do it (eg. that notepad does not exist)

1 = Changed status OK.

Lua example

NotepadReadOnly ("test", true)

Lua notes

The ReadOnly argument is optional and defaults to true.

Jscript example

NotepadReadOnly ("test", true);

VBscript example

NotepadReadOnly "test", vbTrue

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=NotepadReadOnly)


NotepadSaveMethod

Script function

world.NotepadSaveMethod

 Read about scripting

Type

Method

Summary

Changes the save method for this notepad window

Prototype

boolean NotepadSaveMethod(BSTR Title, short Method);

 View list of data type meanings

Description

This lets you change the save method for an open notepad window.

The first argument is the title of an existing notepad window. The second argument is one of the following 3 numbers:

0 - Use default method (same as if this function had not been called)

1 - Always offer to save this window if the contents have changed

2 - Never offer to save this window if the contents have changed

eg.

NotepadSaveMethod ("test", 1)

The following notepad window types normally close without offering to save:

Line Info

MXP debug  (depending on MXP options)

Packet Debug

Plugin Info

XML comments

World Load Error

You could use this to force the saving of something like Packet Debug, or inhibit the saving of a notepad window you created yourself.

Return value

0 = Could not do it (eg. that notepad does not exist, or option out of range)

1 = Option changed OK.

Lua example

NotepadSaveMethod ("test", 1)

Jscript example

NotepadSaveMethod ("test", 1);

VBscript example

NotepadSaveMethod "test", 1

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=NotepadSaveMethod)


NoteStyle

Script function

world.NoteStyle

 Read about scripting

Type

Method

Summary

Sets the style for notes

Prototype

void NoteStyle(short Style);

 View list of data type meanings

Description

This sets the text style for world.note and similar functions.

The styles are 1 bit each, which can be added or OR'ed together.

The style bits are:

  1 = bold

  2 = underline

  4 = blink (italic)

  8 = inverse

 32 = strike-through

Therefore:

NoteStyle (0) resets to normal style.

NoteStyle (1) would be bold.

NoteStyle (3) would be bold and underlined.

Styles are reset to normal when a newline is processed, so if you want to have bold/italic etc. over multiple lines you would need to do the NoteStyle at the start of each line.

You can also use AnsiNote to output styled text.

WARNING: Bold italic, and underlined styles will only be visible if the appropriate configurations are enabled in the world Appearance: Output configuration. Otherwise they will be ignored (the same as for text arriving from the MUD).

Return value

Nothing.

Lua example

NoteStyle (5)  -- bold italic

Note ("hello")

Jscript example

NoteStyle (5);  // bold italic

Note ("hello");

PerlScript example

NoteStyle (5)  # bold italic

Note ("hello")

Python example

NoteStyle (5)  # bold italic

Note ("hello")

VBscript example

NoteStyle 5  ' bold italic

Note "hello"

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 SetNotes (Sets the notes for the world.)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=NoteStyle)


Open

Script function

world.Open

 Read about scripting

Type

Method

Summary

Opens a named document

Prototype

IDispatch* Open(BSTR FileName);

 View list of data type meanings

Description

Returns an object which can be used to refer to the new document (except in Lua, see below).

You should be very cautious about storing the object reference of the world in a global variable, because if the world is closed then that reference becomes invalid, which will very likely lead to an access violation (program crash). You are better off using "world.getworld (name)" every time you need to get a reference to the world, and checking if it "is nothing" as in the example.

Better still, use "world.GetWorldById (id)" which uses each world's unique ID, in case you have multiple worlds of the same name.

You can use Open to open either a MUSHclient world (ie. a MCL file) or a text file (ie. a TXT file).

If the named document is already open then "open" does *not* open another copy, rather it activates that document (brings it to the front).

Return value

For Lua, it returns true if the file was opened OK, and false if not.

For other languages:

An object reference to the named world, if it was found.

Otherwise NULL.

In Vbscript use the test "is nothing" to see if the reference is to a valid world.

In JavaScript use the test "== null" to see if the reference is to a valid world.

In PerlScript use the test "defined ()" to see if the reference is to a valid world.

Lua example

openedOK = world.Open ("smaug.mcl")   -- true or false

Lua notes

Lua is not implemented using the COM model, and thus opening a file and getting an object reference is not possible.

As of version 4.08 however, it will attempt to open the file in the same way as other languages, and return true if it succeeded, and false otherwise.

If you want a "world" userdata to refer to after opening a world, you would need to use GetWorld or GetWorldById to get a reference to the newly-opened world.

Jscript example

var otherworld

   otherworld = world.Open ("smaug.mcl");

  if (otherworld != null)

   otherworld.send("say hi there everyone");

PerlScript example

my $otherworld;

 $otherworld = $world->Open ("smaug.mcl");

  if (!defined ($otherworld))

    {

   $otherworld->send("say hi there everyone");

    }

Python example

var otherworld

   otherworld = world.Open ("smaug.mcl")

  if (otherworld != null)

   otherworld.send("say hi there everyone")

VBscript example

dim otherworld

  set otherworld = world.open  ("smaug.mcl")

  if not (otherworld is nothing) then

    otherworld.send "say hello everyone"

  end if

See Also ...

Topics

 Scripting

 World functions

Functions

 Activate (Activates the world window)

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 OpenBrowser (Opens a supplied URL in your default web browser)

(Help topic: function=Open)


OpenBrowser

Script function

world.OpenBrowser

 Read about scripting

Type

Method

Summary

Opens a supplied URL in your default web browser

Prototype

long OpenBrowser(BSTR URL);

 View list of data type meanings

Description

Opens the URL you supply using the default web browser for this PC.

The URL must start with one of the following strings (not case-sensitive):

http://

https://

mailto:

Return value

eBadParameter - the URL was either empty or did not start with "http://", "https://", or "mailto:".

eCouldNotOpenFile - an error code was returned by Windows when attempting to open the web browser

eOK - successfully opened

 View list of return code meanings

Lua example

OpenBrowser ("http://www.mushclient.com")

Jscript example

OpenBrowser ("http://www.mushclient.com")

PerlScript example

$world->OpenBrowser ("http://www.mushclient.com");

VBscript example

OpenBrowser "http://www.mushclient.com"

See Also ...

Topics

 Scripting

 World functions

Functions

 GetWorld (Gets an object reference to the named world)

 GetWorldById (Gets an object reference to the world given its unique ID)

 GetWorldIdList (Gets the list of open worlds - returning their world IDs)

 GetWorldList (Gets the list of open worlds - returning their world names)

 Open (Opens a named document)

(Help topic: function=OpenBrowser)


OpenLog

Script function

world.OpenLog

 Read about scripting

Type

Method

Summary

Opens a log file.

Prototype

long OpenLog(BSTR LogFileName, BOOL Append);

 View list of data type meanings

Description

This opens a log file of the name "LogFileName", with optional appending to an existing file of the same name. No previous output lines are written (as may happen when you use the ‘open log’ dialog box), nor is a log-file preamble written. If you want to write those things to the script file, you must do them yourself (see WriteLog).

If an empty filename is supplied (that is, "") then the filename specified in the Logging configuration will be used, which lets you use substitutions in the name of the file (eg. the date).

Return value

eOK: opened OK

eCouldNotOpenLogFile: unable to open the log file

eLogFileAlreadyOpen: log file was already open

 View list of return code meanings

Lua example

OpenLog ("mylog.txt", false)

Lua notes

The Append flag is optional, and defaults to false.

Jscript example

world.openlog("mylog.txt", false);

PerlScript example

$world->openlog("mylog.txt", false);

Python example

world.openlog("mylog.txt", False)

VBscript example

world.openlog "mylog.txt", false

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 WriteLog (Writes to the log file)

(Help topic: function=OpenLog)


PasteCommand

Script function

world.PasteCommand

 Read about scripting

Type

Method

Summary

Pastes text into the command window, replacing the current selection

Prototype

BSTR PasteCommand(BSTR Text);

 View list of data type meanings

Description

This pastes the supplied text into the command window, which does not have to be empty (unlike SetCommand) at the current cursor position, replacing any selection. It returns the text that it replaced, if any.

eg.

Command window reads:

go north

^^

("go" is selected)

You execute:  s = PasteCommand ("walk")

Command window now reads:

walk north

s contains "go"

You could use this to make shortcut keys that paste frequently-used words into the command window.

For example:

/Accelerator ("Alt+N", "/PasteCommand 'swordfish'")

Now, whenever you hit Alt+N the word "swordfish" is pasted into the command window, replacing the current selection, or at the cursor.

Return value

The previously selected text, if any.

Lua example

previous = PasteCommand ("swordfish")

Jscript example

PasteCommand ("swordfish");

PerlScript example

$world->PasteCommand ("swordfish");

Python example

PasteCommand ("swordfish")

VBscript example

previous = PasteCommand ("swordfish")

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Accelerator (Add or modify an accelerator key (keystroke to command mapping))

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=PasteCommand)


Pause

Script function

world.Pause

 Read about scripting

Type

Method

Summary

Turns pause mode on or off

Prototype

void Pause(BOOL Flag);

 View list of data type meanings

Description

Turns on or off the "paused" flag for all output windows in this world.

Return value

Nothing

Lua example

Pause (true)  -- pause the world

Pause (false) -- unpause the world

Lua notes

The argument is optional, and defaults to true.

Jscript example

world.Pause (true);  // pause the world

world.Pause (false); // unpause the world

PerlScript example

$world->pause(true);  # pause the world

$world->pause(false); # unpause the world

Python example

world.Pause (True)  # pause the world

world.Pause (False) # unpause the world

VBscript example

world.Pause vbTrue  ' pause the world

world.Pause vbFalse ' unpause the world

(Help topic: function=Pause)


PickColour

Script function

world.PickColour

 Read about scripting

Type

Method

Summary

Invokes the MUSHclient colour picker dialog

Prototype

long PickColour(long Suggested);

 View list of data type meanings

Description

This lets you call the MUSHclient colour picker from within a script. Note that doing this will pause script execution while the dialog is active, and is not recommended for scripts that should run to completion quickly.

eg.

  newcolour = PickColour (254)

You supply an existing colour as the starting point, or -1 if none is required, and the function returns the chosen colour, or -1 if the dialog was cancelled. Note that -1 is not a valid colour.

Return value

The chosen colour, or -1 if the dialog box was dismissed.

Lua example

newcolour = PickColour (255)

Jscript example

newcolour = PickColour (255);

PerlScript example

newcolour  = $world->PickColour (255)

Python example

newcolour = world.PickColour (255);

VBscript example

newcolour = PickColour (255)

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 Debug (Displays debugging information about the world)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=PickColour)


PlaySound

Script function

world.PlaySound

 Read about scripting

Type

Method

Summary

Plays a sound using DirectSound

Prototype

long PlaySound(short Buffer, BSTR FileName, BOOL Loop, double Volume, double Pan);

 View list of data type meanings

Description

Plays a sound, or adjusts the parameters of a sound that is currently playing.

Also see below in the Lua notes for PlaySoundMemory which plays a sound loaded into memory.

You can choose to use 1 of 10 "sound buffers" - sounds placed in different buffers will play simultaneously.

If a sound is currently playing in the selected buffer it is automatically stopped and its memory freed. Thus you do not need to stop sounds first before replacing them by something else.

See: http://mushclient.com/forum/?id=8721 for a more detailed description.

You can use StopSound to stop the sound playing at any time, and GetSoundStatus to see if a sound is playing or not in a particular buffer.

------------

Buffer: Which buffer to use (1 to 10) or 0 to take the first free buffer when playing a new sound. If there are no free buffers, buffer 1 is chosen.

------------

FileName: The sound file to play. Can be the empty string in which case you are modifying the behaviour of a currently-playing sound in that buffer.

If the file name is a fully-qualified path name (ie. it starts with a slash, or a drive letter, colon, slash like "C:/") then it is used "as is".

Otherwise, MUSHclient prepends the MUSHclient execution directory + "sounds" subdirectory to the name

For example, the file name "swordhit.wav" would be looked for at: C:/Program Files/MUSHclient/sounds/swordhit.wav

You can use forward slashes in the file name (for convenience in typing strings in scripts), they are converted to backslashes.

The only file type supported is a .wav file, as follows:

* 16-bit

* 22.05 KHz

* PCM (ie. uncompressed)

* Mono or Stereo

Note that the entire file is read into memory, uncompressed. We do not attempt to "stream" the file. Thus large sound files will take a lot of memory. The sound functions are intended for sound effects and short loops of music or ambient sounds. They are not intended to play Beethoven's Fifth Symphony while you play.

You can convert sound files which are in other formats (eg. MP3) into WAV files by using various programs. One very good free program is Audacity, which is available for Mac or Windows:

http://audacity.sourceforge.net/

In Audacity, open your file, and then choose: File Menu -> Export As WAV...

------------

Loop: true or false (1 or 0). If true the sound loops, and thus repeats indefinitely until cancelled. A sound can be cancelled by calling the StopSound function for that buffer number, or simply playing a different sound in that buffer. Obviously it is preferable to not use buffer 0 if you are planning to loop, because you won't know which buffer actually got allocated.

If omitted in Lua scripting this defaults to false (not looping).

------------

Volume: -100 to 0. This is the number of db (decibels) to attenuate (reduce) the sound. Decibels are a logarithmic scale, every 3 db corresponds to half the perceived sound volume. Thus a volume of zero is "full volume". A volume of -3 is half-volume, -6 is quarter-volume, and so on. If you want to fade a sound away rather than just cut if off, you get quite a good effect by readjusting the sound every half second or so in a loop, reducing the volume by -2 each time, from 0 to -40. A sound at volume -40 is pretty quiet, after which you can just stop playing the sound. If you are going to write a "reduce the volume" loop you would need to use Lua coroutines, or some other timer mechanism, to turn the volume in that channel down periodically.

If omitted in Lua scripting this defaults to 0 (full volume).

If the volume is out of the range -100 to 0 then 0 (full volume) is used.

------------

Pan: -100 to +100. This is the number of db (decibels) to attenuate the sound in one speaker, to create a stereo affect (that is, more from one speaker than the other).

Pan of -100 makes the sound come completely from the left speaker (the right speaker is cut off).

Pan of 0 makes the sound come from both speakers, and thus it sounds centered.

Pan of +100 makes the sound come completely from the right speaker (the left speaker is cut off).

If omitted in Lua scripting this defaults to 0 (both speakers, or centered).

If the pan value is out of the range -100 to +100 then 0 is used.

-----------

Playing sounds in the background ...

The default behaviour is for the sounds to be only played if MUSHclient is currently active (the foreground window, that is). If you switch to another application the sound will cut out (and resume if it is still playing when you switch back).

To have the sound play regardless, you need to set a world configuration option, like this:

SetOption ("play_sounds_in_background", 1)

That option only needs to be set once per world file. Once the world file is saved to disk the option will persist.

Return value

eCannotPlaySound:

* DirectSound not initialized

* An attempt made to change the volume, looping, or pan of a sound that is not playing

* Sound file is not a .wav file

* Cannot parse sound file

* Sound file is not a PCM format file (wrong sound file format)

* Cannot find sound data in sound file

* Cannot create internal sound buffer (maybe all in use)

* Cannot read sound data into memory

* DirectSound refuses to play the sound

eBadParameter:

* An attempt made to change the volume, looping, or pan of a sound that is not in use

* No sound file name given, and buffer 0 given

* Buffer number outside range 0 to 10

* File name > 127 characters long

eFileNotFound:

* Sound file not found

eOK:

* Sound played OK (or volume/looping/pan adjusted OK)

 View list of return code meanings

Lua example

-- play sound once only, full volume, centered, in buffer 1

PlaySound (1, "boing.wav", false, 0, 0)

-- play sound once only, quarter volume, from the left speaker, in buffer 2

PlaySound (2, "ding.wav", false, -6, -100)

-- play sound looping, eighth volume, from the right speaker, in buffer 3

PlaySound (3, "forest.wav", true, -9, 100)

-- play sound once only, full volume, slightly to the left, in the first available buffer

PlaySound (0, "swordhit.wav", false, 0, -3)

To adjust an existing sound, like the forest sound above:

PlaySound (3, "", false, -9, 100)  --> cancel looping for buffer 3, still play at -9 db

PlaySound (3, "", false, -12, 100)  --> cancel looping for buffer 3 and make softer

To wait until a previous sound has finished playing:

require "wait"

function PlayOneSound (name)

  wait.make ( function ()

    while GetSoundStatus (1) > 0 do

      wait.time (0.1)

    end -- while previous sound still playing

    PlaySound (1, name)

  end )  -- end of wait.make

end -- PlayOneSound

PlayOneSound ("1.wav")

PlayOneSound ("2.wav")

PlayOneSound ("3.wav")

Lua notes

All arguments except the buffer number are optional.

The file name defaults to the empty string, looping defaults to false, volume defaults to full volume, and panning defaults to centered.

From version 4.42 onwards, Lua also supports PlaySoundMemory which plays a sound file loaded into a memory buffer.

In this case the second argument is the memory buffer, not the file name.

local f = assert (io.open ("some_sound.wav", "rb"))

local sound_data = f:read ("*a")  -- read all of it

f:close ()  -- close it

PlaySoundMemory (1, sound_data, false, 0, 0)  -- play sound loaded into sound_data

VBscript example

' play sound once only, full volume, centered, in buffer 1

PlaySound 1, "boing.wav", vbFalse, 0, 0

' play sound once only, quarter volume, from the left speaker, in buffer 2

PlaySound 2, "ding.wav", vbFalse, -6, -100

' play sound looping, eighth volume, from the right speaker, in buffer 3

PlaySound 3, "forest.wav", vbTrue, -9, 100

' play sound once only, full volume, slightly to the left, in the first available buffer

PlaySound 0, "swordhit.wav", vbFalse, 0, -3

'  To adjust an existing sound, like the forest sound above:

PlaySound 3, "", vbFalse, -9, 100  ' cancel looping for buffer 3, still play at -9 db

PlaySound 3, "", vbFalse, -12, 100 ' cancel looping for buffer 3 and make softer

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 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)

 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=PlaySound)


PluginSupports

Script function

world.PluginSupports

 Read about scripting

Type

Method

Summary

Checks if a plugin supports a particular routine

Prototype

long PluginSupports(BSTR PluginID, BSTR Routine);

 View list of data type meanings

Description

Checks to see if a specified plugin exists, and supports a specified routine.

For example:

If world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") <> eOK then

  world.Note "Required 'LogIt' routine is not available"

End If

Return value

eNoSuchPlugin: Plugin not installed

eNoSuchRoutine: Specified routine cannot be found in that plugin

eOK: Called OK

 View list of return code meanings

Lua example

if PluginSupports ("80cc18937a2aca27079567f0", "LogIt") ~= error_code.eOK then

  Note ("Required 'LogIt' routine is not available")

end

Jscript example

If (world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != eOK)

  {

  world.Note ("Required 'LogIt' routine is not available");

  }

PerlScript example

if ($world->PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != eOK)

 {

 $world->Note ("Required 'LogIt' routine is not available");

 }

Python example

if world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") != 0:

  world.Note ("Required 'LogIt' routine is not available")

VBscript example

If world.PluginSupports ("80cc18937a2aca27079567f0", "LogIt") <> eOK then

  world.Note "Required 'LogIt' routine is not available"

End If

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=PluginSupports)


PushCommand

Script function

world.PushCommand

 Read about scripting

Type

Method

Summary

Pushes the current command into the command history list

Prototype

BSTR PushCommand();

 View list of data type meanings

Description

Pushes the current contents of the command window into the command history list, and then blanks the current command.

You could use this prior to doing SetCommand, as SetCommand will not work with a command in the command window.

This function returns the text of the command that was in the command window, in case you want to restore it later.

If more than one window is open for this world, it uses the first window in the window list.

Return value

The original contents of the command window.

Lua example

PushCommand ()

Jscript example

world.PushCommand ();

PerlScript example

$world->PushCommand ();

Python example

world.PushCommand

VBscript example

world.PushCommand

See Also ...

Functions

 GetCommand (Gets the current command in the command window)

 GetCommandList (Returns some or all commands from the command history)

 SelectCommand (Selects (highlights) the current command in the command window)

 SetCommand (Sends text to the command window)

(Help topic: function=PushCommand)


Queue

Script function

world.Queue

 Read about scripting

Type

Method

Summary

Queues a command for sending at the "speed walk" rate.

Prototype

long Queue(BSTR Message, boolean Echo);

 View list of data type meanings

Description

Queues the supplied command for sending to the MUD at the designated "speed walk" rate. This is for sending commands slowly, because quick sending might be inappropriate.

If the speed walk delay (SpeedWalkDelay property) is zero, then using Queue is exactly the same as using Send.

If Echo is true then the commands are echoed to the output window (as they are sent, not as they are queued).

If the speed walk delay is not zero, then the supplied message is appended to the end of the command queue. The command is split up at line breaks (whenever a carriage-return/linefeed combination is found), and each line is sent, separated by a delay of SpeedWalkDelay milliseconds.

Periodically (every SpeedWalkDelay milliseconds) the command at the top of the command queue is retrieved and sent to the MUD, and echoed in the output window if required.

If you want to bypass the queue (eg. to say something) then use SendImmediate.

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Queued OK

 View list of return code meanings

Lua example

Queue (EvaluateSpeedwalk("4n"), true)

Lua notes

The echo flag is optional, and defaults to true.

Jscript example

world.queue(world.evaluatespeedwalk("4n"), true);

PerlScript example

$world->queue($world->evaluatespeedwalk("4n"), true);

Python example

world.queue(world.evaluatespeedwalk("4n"), True)

VBscript example

world.queue world.evaluatespeedwalk ("4n"), true

See Also ...

Functions

 DiscardQueue (Discards the speed walk queue)

 EvaluateSpeedwalk (Evaluates a speed walk string)

 GetQueue (Returns a variant array which is a list of queued commands)

 Note (Sends a note to the output window)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=Queue)


ReadNamesFile

Script function

world.ReadNamesFile

 Read about scripting

Type

Method

Summary

Loads in a file for generating character names

Prototype

long ReadNamesFile(BSTR FileName);

 View list of data type meanings

Description

This is used to load in a file of character names for the random name generator.

The names file should be loaded before calling GenerateName.

The file should contain lines with "[start]", "[middle]", "[end]" and "[stop]" in it (see below for example). Using the example file below, a generated name might be Wicorebwyn  (Wic - ore - bwyn). By setting up different files you can generate names with a different "feel" to them.

Example names file:

[start]

A

Ab

Ac

Ad

W

Wic

[middle]

a

ae

ore

u

y

[end]

a

and

b

bwyn

baen

bard

[stop]

Return value

eNoNameSpecified: File name cannot be blank

eCouldNotOpenFile: Could not open file, or file was not a valid names file

eOK: Processed file OK

 View list of return code meanings

Lua example

ReadNamesFile ("mynames.nam")

Jscript example

world.readnamesfile("mynames.nam");

PerlScript example

$world->readnamesfile("mynames.nam");

Python example

world.readnamesfile("mynames.nam")

VBscript example

world.readnamesfile "mynames.nam"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 Replace (Replaces one substring with another)

 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)

 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=ReadNamesFile)


Redraw

Script function

world.Redraw

 Read about scripting

Type

Method

Summary

Schedules a redraw for all windows for this world

Prototype

void Redraw();

 View list of data type meanings

Description

Schedules a redraw of all windows for this world. Use this after changing colours, or changing miniwindows.

Note that the main window is not actually redrawn at this point, however it is scheduled for redraw next time through the main event loop.

Return value

Nothing.

Lua example

Redraw ()

Jscript example

Redraw();

PerlScript example

$world->Redraw();

Python example

Redraw

VBscript example

Redraw

See Also ...

Functions

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 Repaint (Forces an immediate redraw for all windows for this world)

(Help topic: function=Redraw)


ReloadPlugin

Script function

world.ReloadPlugin

 Read about scripting

Type

Method

Summary

Reloads an installed plugin

Prototype

long ReloadPlugin(BSTR PluginID);

 View list of data type meanings

Description

This is designed to help plugin writers quickly reload a plugin they are testing. You can specify the plugin by unique ID, or by plugin name (assuming the name is unique in your list of plugins).

eg.

world.ReloadPlugin "chat"

world.ReloadPlugin "753ba7e011f3c8943a885f18"

However, a plugin cannot reload itself. That would mean the script was deleted out from under itself. If you try to work around that by having plugin A call plugin B, and plugin B reloads plugin A, you will probably get a crash. If you really want to make a "reload myself" function in a plugin, use something like DoAfterSpecial, to send the "ReloadPlugin" command to the script engine after a 1-second delay.

The intention here is for plugin authors to make an alias that they can type when they want to retest their plugin.

The check for plugin name or plugin ID is not case-sensitive.

Return value

eNoSuchPlugin: Plugin is not currently installed

eBadParameter: Cannot reload ourselves

ePluginFileNotFound: Plugin file not found

eProblemsLoadingPlugin: Parsing or other problem in plugin file - see error window

eOK: Loaded OK

 View list of return code meanings

Lua example

ReloadPlugin ("chat")

ReloadPlugin ("753ba7e011f3c8943a885f18")

Jscript example

world.ReloadPlugin ("chat");

world.ReloadPlugin ("753ba7e011f3c8943a885f18");

PerlScript example

$world->ReloadPlugin ("chat");

$world->ReloadPlugin ("753ba7e011f3c8943a885f18");

Python example

world.ReloadPlugin ("chat")

world.ReloadPlugin ("753ba7e011f3c8943a885f18")

VBscript example

world.ReloadPlugin "chat"

world.ReloadPlugin "753ba7e011f3c8943a885f18"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 SaveState (Saves the state of the current plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=ReloadPlugin)


RemoveBacktracks

Script function

world.RemoveBacktracks

 Read about scripting

Type

Method

Summary

Removes backtracks from a speed walk string

Prototype

BSTR RemoveBacktracks(BSTR Path);

 View list of data type meanings

Description

This takes a speedwalk as an argument and removes any backtracks from it.

For example:  "4n 2s" would be converted to "2n".

A side-effect of this routine is that comments will be removed from speedwalks, and "reverse direction hints" will also be removed. eg. "(open door/close door) {comment}" would be converted to "(open door)".

It will also join directions where possible, eg. "n n n" would become "3n"

Return value

The supplied string, with the backtracks removed as described above.

If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.

Lua example

Note(RemoveBacktracks("4n 2s"))

Jscript example

world.note(world.RemoveBacktracks("4n 2s"));

PerlScript example

$world->note($world->RemoveBacktracks("4n 2s"));

Python example

world.note(world.RemoveBacktracks("4n 2s"))

VBscript example

world.note world.RemoveBacktracks("4n 2s")

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

 Speed walking

Functions

 EvaluateSpeedwalk (Evaluates a speed walk string)

 ReverseSpeedwalk (Reverses a speed walk string)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=RemoveBacktracks)


RemoveMapReverses

Script function

world.RemoveMapReverses

 Read about scripting

Type

Property

Summary

A flag to indicate whether we backtracks are removed during mapping

Prototype

boolean RemoveMapReverses;

 View list of data type meanings

Description

This property controls whether backtracks are removed from the auto-mapper as you walk around.

Return value

TRUE if backtracks are removed

FALSE if backtracks are NOT removed

Note: TRUE is a non-zero value, FALSE is the value 0.

Lua example

Note(GetRemoveMapReverses ())

Lua notes

Lua implements this as two functions:

GetRemoveMapReverses - gets the 'remove map reverses' flag

SetRemoveMapReverses - sets the 'remove map reverses' flag

Jscript example

world.note(world.RemoveMapReverses);

PerlScript example

$world->note ($world->{RemoveMapReverses});

Python example

world.note(world.RemoveMapReverses)

VBscript example

world.note world.RemoveMapReverses

See Also ...

Topics

 Aliases

 Auto-mapper

 Speed walking

Functions

 AddMapperComment (Adds a comment to the auto-map sequence)

 AddToMapper (Adds a mapping direction to the auto-map sequence)

 DeleteAllMapItems (Deletes the all items from the auto-mapper sequence.)

 DeleteLastMapItem (Deletes the most recently-added item from the auto-mapper sequence.)

 EnableMapping (Enables or disables the auto-mapper)

 GetMappingCount (Gets a count of the number of items in the auto-map sequence)

 GetMappingItem (Gets one item from the auto-map sequence)

 GetMappingString (Returns the speedwalk string generated by the auto-mapper.)

 Mapping (A flag to indicate whether we are mapping the world)

(Help topic: function=RemoveMapReverses)


Repaint

Script function

world.Repaint

 Read about scripting

Type

Method

Summary

Forces an immediate redraw for all windows for this world

Prototype

void Repaint();

 View list of data type meanings

Description

This function forces the output window to be redrawn. This should not normally be called, as the window will be redrawn at the appropriate time through the main "event loop".

Unnecessary calls to Repaint will slow the program down.

However for "animation" situations (like moving an image over a map) there may be times when you actually want the window redrawn, between "frames". In this case, you could call Repaint to force an immediate redraw.

Otherwise, use Redraw instead, which will cause the window to be redrawn at the next appropriate opportunity.

Return value

Nothing.

Lua example

Repaint ()

Jscript example

Repaint();

PerlScript example

$world-> Repaint();

Python example

Repaint

VBscript example

Repaint

See Also ...

Functions

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 Redraw (Schedules a redraw for all windows for this world)

(Help topic: function=Repaint)


Replace

Script function

world.Replace

 Read about scripting

Type

Method

Summary

Replaces one substring with another

Prototype

BSTR Replace(BSTR Source, BSTR SearchFor, BSTR ReplaceWith, boolean Multiple);

 View list of data type meanings

Description

This is a utility function for doing a "find and replace" inside a string.

It is intended to simplify writing scripts that need to replace things.

If "Multiple" is true then all occurences are replaced, otherwise only the first one is replaced.

Return value

The source string with one or more occurences of "SearchFor" replaced by "ReplaceWith".

Lua example

Note(Replace("go north, go east", "go", "walk", true))

Lua notes

The Multiple flag is optional, and defaults to true.

Jscript example

world.Note(world.Replace("go north, go east", "go", "walk", true));

PerlScript example

$world->Note($world->Replace("go north, go east", "go", "walk", true));

Python example

world.Note(world.Replace("go north, go east", "go", "walk", True))

VBscript example

world.Note world.Replace ("go north, go east", "go", "walk", true)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=Replace)


ReplaceNotepad

Script function

world.ReplaceNotepad

 Read about scripting

Type

Method

Summary

Replaces text in a notepad window

Prototype

boolean ReplaceNotepad(BSTR Title, BSTR Contents);

 View list of data type meanings

Description

Replaces  the text in a notepad window of the given title. If no such window exists, it is created.

The function "ReplaceNotepad" does not activate (bring to the front) the notepad window. However the function "ActivateNotepad" can be used to do that.

You can use world.activate to activate the world itself (eg. you might want to do that after creating a notepad window).

Return value

0: Could not do it.

1:  Replaced OK

Lua example

ReplaceNotepad("Nick's window", "New contents\r\n")

Lua notes

You can supply multiple arguments after the notepad name, which are concatenated together.

Jscript example

world.ReplaceNotepad("Nick's window", "New contents\r\n");

PerlScript example

$world->ReplaceNotepad("Nick's window", "New contents\r\n");

Python example

world.ReplaceNotepad("Nick's window", "New contents\r\n")

VBscript example

world.ReplaceNotepad "Nick's window", "New contents" + vbcrlf

See Also ...

Topic

 Notepad

Functions

 Activate (Activates the world window)

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 SaveNotepad (Saves a notepad window to disk)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=ReplaceNotepad)


Reset

Script function

world.Reset

 Read about scripting

Type

Method

Summary

Resets all outstanding MXP/Pueblo tags

Prototype

void Reset();

 View list of data type meanings

Description

This closes any outstanding MXP/Pueblo tags, and resets the output window colours to ANSI white on black. It also cancels underline, highlight, and inverse.

Return value

Nothing.

Lua example

Reset()

Jscript example

world.Reset();

PerlScript example

$world->Reset();

Python example

world.Reset

VBscript example

world.reset

(Help topic: function=Reset)


ResetIP

Script function

world.ResetIP

 Read about scripting

Type

Method

Summary

Resets the cached IP address of the world and proxy server

Prototype

void ResetIP();

 View list of data type meanings

Description

Call this function to reset the internal copy of the world's IP address, saved after looking up its domain name.

This would be useful if you connect to worlds that frequenly change their address, otherwise the old (cached) one would be used when you connect to the world the second and subsequent times.

Return value

Nothing.

Lua example

ResetIP ()

Jscript example

ResetIP ()

VBscript example

ResetIP

See Also ...

Functions

 Connect (Connects the world to the MUD server)

 Disconnect (Disconnects the world from the MUD server)

(Help topic: function=ResetIP)


ResetStatusTime

Script function

world.ResetStatusTime

 Read about scripting

Type

Method

Summary

Resets the time elapsed shown on the status bar

Prototype

void ResetStatusTime();

 View list of data type meanings

Description

This resets the "connect time" to now, so that the time shown on the status bar counts up from the moment you called this function.

Return value

Nothing.

Lua example

ResetStatusTime()

Jscript example

world.ResetStatusTime();

PerlScript example

$world->ResetStatusTime();

Python example

world.ResetStatusTime

VBscript example

world.ResetStatusTime

(Help topic: function=ResetStatusTime)


ResetTimer

Script function

world.ResetTimer

 Read about scripting

Type

Method

Summary

Resets a named timer

Prototype

long ResetTimer(BSTR TimerName);

 View list of data type meanings

Description

Resets the named timer.

Also see ResetTimers to reset all timers.

WARNING - timers that are not enabled will not be reset. Use EnableTimer first to make sure the timer is enabled, before resetting it, if necessary.

Return value

eInvalidObjectLabel: The timer name is not valid

eTimerNotFound: The timer does not exist

eOK: reset OK

 View list of return code meanings

Lua example

ResetTimer("mytimer")

Jscript example

world.ResetTimer("mytimer");

PerlScript example

$world->ResetTimer("mytimer");

Python example

world.ResetTimer("mytimer")

VBscript example

world.ResetTimer "mytimer"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimers (Resets all timers)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=ResetTimer)


ResetTimers

Script function

world.ResetTimers

 Read about scripting

Type

Method

Summary

Resets all timers

Prototype

void ResetTimers();

 View list of data type meanings

Description

Resets all timers for the world. There is no return value.

This function will reset all periodic timers to fire from the appropriate interval from when the "ResetTimers" was done.

WARNING - timers that are not enabled will not be reset. Use EnableTimer first to make sure that timers are enabled, before resetting them, if necessary.

Return value

Nothing.

Lua example

ResetTimers()

Jscript example

world.ResetTimers();

PerlScript example

$world->ResetTimers();

Python example

world.ResetTimers

VBscript example

world.ResetTimers

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 SetTimerOption (Sets the value of a named timer option)

(Help topic: function=ResetTimers)


ReverseSpeedwalk

Script function

world.ReverseSpeedwalk

 Read about scripting

Type

Method

Summary

Reverses a speed walk string

Prototype

BSTR ReverseSpeedwalk(BSTR SpeedWalkString)

 View list of data type meanings

Description

Reverses a supplied string based on the rules for "speed walking". See EvaluateSpeedwalk for a detailed description of those rules.

For example:

4n 3e s u w d LW

When reversed, this would become:

LE U E D N 3W 4S

If you supply a "special string" in parentheses, then the order of the words in parentheses is reversed. This lets you do special actions (eg. NE for NorthEast), and supply the reverse direction.

For example:

4n (se/nw)(in/out)

This would become:

(out/in) (nw/se) 4S

Return value

The supplied string, with the speedwalk directions reversed as described above.

If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.

Lua example

Note(ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"))

Jscript example

world.note(world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"));

PerlScript example

$world->note($world->ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"));

Python example

world.note(world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)"))

VBscript example

world.note world.ReverseSpeedwalk ("4n3esuwdLW(ne/sw)")

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

 Speed walking

Functions

 EvaluateSpeedwalk (Evaluates a speed walk string)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=ReverseSpeedwalk)


RGBColourToName

Script function

world.RGBColourToName

 Read about scripting

Type

Method

Summary

Converts an RGB colour code to its equivalent name

Prototype

BSTR RGBColourToName(long Colour);

 View list of data type meanings

Description

Converts an RGB colour code (eg. 255) to its HTML name (eg. "red").

If the name is not in the list of names recognised by MUSHclient, the colour is represented as a hex HTML colour (eg. "#010203").

The list of colour names recognised can be found by using MUSHclient's "colour picker" (Ctrl+Alt+P), or by using the function:

world.Debug "colours"

Return value

The colour name (eg. "red", "blue"), or an RGB code (eg. "#FFE4E1).

Lua example

Note (RGBColourToName (255))

Jscript example

world.note (world.RGBColourToName (255));

PerlScript example

$world->note ($world->RGBColourToName (255));

Python example

world.note (world.RGBColourToName (255))

VBscript example

world.note world.RGBColourToName (255)

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 Debug (Displays debugging information about the world)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 SetCustomColourName (Sets the name of a custom colour)

(Help topic: function=RGBColourToName)


Save

Script function

world.Save

 Read about scripting

Type

Method

Summary

Saves world configuration.

Prototype

boolean Save(BSTR Name);

 View list of data type meanings

Description

Saves the current world, under the specified filename. Supply a blank file name to save under the current name.

Also, all plugins are forced to save their current state.

Under Lua (only) you can do a "save as" which saves under a new name, but preserves the original name, see below.

Return value

eOK: saved OK

any other value: not saved

Under Lua:

false: saved OK

true: did not save OK

 View list of return code meanings

Lua example

Save("")   -- Saves under current name

Save ("my_new_name.mcl")  -- Save under a new name - which is used for future saves

Save ("my_backup.mcl", true)  -- Save a copy under a different name, original name is unchanged

Lua notes

The filename is optional, if not supplied the file is saved under its current name, if any.

You can supply a second boolean argument. If true, MUSHclient does a "save as", which means the file is saved under the given name, however the original name is preserved for future save. If you do a "save as" the file name is not optional.

Note under Lua the return codes are a bit misleading:

false: saved OK

true: did not save OK

Jscript example

world.Save("");   // Saves under current name

PerlScript example

$world->Save("");   # Saves under current name

Python example

world.Save("")   # Saves under current name

VBscript example

world.Save ""   ' Saves under current name

world.Save "my_new_name.mcl"  ' Saves under new name

(Help topic: function=Save)


SaveNotepad

Script function

world.SaveNotepad

 Read about scripting

Type

Method

Summary

Saves a notepad window to disk

Prototype

long SaveNotepad(BSTR Title, BSTR FileName, BOOL ReplaceExisting);

 View list of data type meanings

Description

This saves an existing notepad window to disk.

Title - title of the notepad (used in functions like AppendToNotepad)

FileName - name to save to disk as.

If the file name is empty (ie. "") then it will be saved under its existing file name, if any, or you will be prompted for the name to save it as.

ReplaceExisting:

If true - the specified file name becomes the "default" file name for the file. In other words, if you subsequently save from the GUI interface it will automatically use that file.

If false - saves the file under the name you specify, however the "default" file name is unchanged.

WARNING - if a file of the same name exists on disk it will be overwritten, regardless of the ReplaceExisting flag value.

SECOND WARNING - versions 4.13 and earlier of MUSHclient returned 0 on a good save and 1 on a bad save. From version 4.14 onwards it returns 0 on a bad save and 1 on a good save.

Return value

1 = saved OK

0 = not saved

Lua example

SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0)

Lua notes

The ReplaceExisting flag is optional, and defaults to false.

Jscript example

world.SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0);

PerlScript example

$world->SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0);

Python example

world.SaveNotepad ("my_notepad", "c:/mushclient/notepad.txt", 0)

VBscript example

world.SaveNotepad "my_notepad", "c:/mushclient/notepad.txt", 0

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SendToNotepad (Creates a notepad and sends text to it)

(Help topic: function=SaveNotepad)


SaveState

Script function

world.SaveState

 Read about scripting

Type

Method

Summary

Saves the state of the current plugin

Prototype

long SaveState();

 View list of data type meanings

Description

This causes the current plugin to save its state (ie. its variables) to its "state" file. You might call this in a timer every couple of minutes to ensure that variables are saved in the event of a program or computer crash.

If a plugin has:

  save_state="y"

in its plugin configuration (header), then its state is saved automatically as described below.

Plugins automatically save their state when they are closed (ie. when they are uninstalled, or when the world closes), and when the world file is saved. However if the world does not close for days then you may want to arrange for the plugin to save its state more often, particularly if the variables that the plugin is using are valuable.

The plugins by default save their state to a directory called "state" which is a subdirectory of the nominated "world plugins directory". If no such directory exists, then the plugin cannot save its state. The "save state" directory can be found by doing GetInfo (85).

There is a state file for each world/plugin combination.

The file name will look like this:

a282eaabbecd18a56aa07f84-c8efc9f9e1edd118c6f2dbf5-state.xml

This is:

(world ID)-(plugin ID)-state.xml

Each world should have a unique ID, and each plugin should have a unique ID, thus each world's plugin's state should have a unique file name.

Plugins are also forced to save their state when the main world file is saved (ie. world.Save is called, or you save the world file from the File menu).

If the plugin has an OnPluginSaveState function this is called before the state is saved - this lets the plugin serialize its script variables - that is, convert from script internal variables to MUSHclient variables.

If a plugin is not executing (that is, if this is called from outside a plugin execution) then no state can be saved and an error code is returned.

Prior to version 4.56 a plugin could not save its state by calling this function unless save_state was set as "y" in the plugin header.

Return value

eNotAPlugin: Script is not currently executing inside a plugin.

ePluginCouldNotSaveState: The plugin could not save its state (eg. no "state" directory, disk full, not permitted)

eOK: Plugin saved its state OK.

 View list of return code meanings

Lua example

SaveState ()

Lua notes

See the forum thread http://www.gammon.com.au/forum/?id=4960 for suggestions about how to serialize Lua tables into a variable. This has example OnPluginSaveState functions.

Jscript example

world.SaveState ();

PerlScript example

$world->SaveState ();

Python example

world.SaveState

VBscript example

world.SaveState

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 UnloadPlugin (Unloads an installed plugin)

(Help topic: function=SaveState)


SelectCommand

Script function

world.SelectCommand

 Read about scripting

Type

Method

Summary

Selects (highlights) the current command in the command window

Prototype

void SelectCommand();

 View list of data type meanings

Description

Selects the command in the command window.

The intention here is to be used by scripts that place text in the command window. By selecting it, the player can discard the selected command by simply starting to type.

If more than one window is open for this world, it uses the first window in the window list.

Return value

Nothing.

Lua example

SelectCommand ()

Jscript example

world.SelectCommand ();

PerlScript example

$world->SelectCommand ();

Python example

world.SelectCommand

VBscript example

world.SelectCommand

See Also ...

Functions

 GetCommand (Gets the current command in the command window)

 GetCommandList (Returns some or all commands from the command history)

 PushCommand (Pushes the current command into the command history list)

 SetCommand (Sends text to the command window)

(Help topic: function=SelectCommand)


Send

Script function

world.Send

 Read about scripting

Type

Method

Summary

Sends a message to the MUD

Prototype

long Send(BSTR Message);

 View list of data type meanings

Description

This sends the specified text to the world. It is similar to typing it into the command window. However aliases, speedwalks, scripting prefixes, command-stacking etc. are not evaluated.

If you want to exactly emulate typing into the command window use world.Execute instead.

Use Send to send things to the MUD without further evaluation. Use Execute to allow other aliases to process what you sent.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines.

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is not saved in the command history buffer (use SendPush if you want to save it).

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

Send ("go north")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.Send("go north");

PerlScript example

$world->Send("go north");

Python example

world.Send("go north")

VBscript example

world.send "go north"

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Execute (Executes a command as if you had typed it into the command window)

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Queue (Queues a command for sending at the "speed walk" rate.)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=Send)


SendImmediate

Script function

world.SendImmediate

 Read about scripting

Type

Method

Summary

Sends a message to the MUD immediately, bypassing the speedwalk queue

Prototype

long SendImmediate(BSTR Message);

 View list of data type meanings

Description

This sends the specified text to the world. It is like typing it into the command window. If there is a queue of commands in the speedwalk queue, this command "jumps the queue" - that is, it gets sent immediately.

The intention here is to use it for commands (like "say", "tell") that are not dependent on a speedwalk sequence finishing.

The command is not saved in the command history buffer nor is it logged.

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

SendImmediate ("go north")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.SendImmediate("go north");

PerlScript example

$world->SendImmediate("go north");

Python example

world.SendImmediate("go north")

VBscript example

world.SendImmediate "go north"

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Execute (Executes a command as if you had typed it into the command window)

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Queue (Queues a command for sending at the "speed walk" rate.)

 Send (Sends a message to the MUD)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SendImmediate)


SendNoEcho

Script function

world.SendNoEcho

 Read about scripting

Type

Method

Summary

Sends a message to the MUD without echoing in the output window

Prototype

long SendNoEcho(BSTR Message);

 View list of data type meanings

Description

This sends the specified text to the world. It is like typing it into the command window. The command is not echoed in the output window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines.

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is not saved in the command history buffer (use SendPush if you want to save it).

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

SendNoEcho("go north")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.SendNoEcho("go north");

PerlScript example

$world->SendNoEcho("go north");

Python example

world.SendNoEcho ("go north")

VBscript example

world.SendNoEcho "go north"

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Execute (Executes a command as if you had typed it into the command window)

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Queue (Queues a command for sending at the "speed walk" rate.)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SendNoEcho)


SendPkt

Script function

world.SendPkt

 Read about scripting

Type

Method

Summary

Sends a low-level packet of data to the MUD

Prototype

long SendPkt(BSTR Packet);

 View list of data type meanings

Description

This sends the specified text to the world.

A newline is not appended to it.

If the text contains the IAC character (0xFF) a second IAC character is NOT appended to it (as normally happens).

The text does not go through the OnPluginSend plugin callback, nor through the OnPluginSent callback.

The text is not echoed to the screen.

It is intended only for low-level sending of data for things like telnet negotiation options.

Return value

eWorldClosed : The world is closed

eOK: Sent OK

 View list of return code meanings

Lua example

SendPkt (string.char (255, 252, 31))  -- IAC WONT NAWS

Lua notes

The data may include imbedded null characters (0x00) as the Lua string is not tested for being null-terminated.

VBscript example

SendPkt Chr(255) & Chr (252) & Chr (31)  ' IAC WONT NAWS

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Execute (Executes a command as if you had typed it into the command window)

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Queue (Queues a command for sending at the "speed walk" rate.)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SendPkt)


SendPush

Script function

world.SendPush

 Read about scripting

Type

Method

Summary

Sends a message to the MUD and saves it in the command history buffer

Prototype

long SendPush(BSTR Message);

 View list of data type meanings

Description

This sends the specified text to the world. It is like typing it into the command window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines.

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

The command is saved in the command history buffer (use Send if you do NOT want to save it).

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

SendPush ("go north")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.SendPush("go north");

PerlScript example

$world->SendPush("go north");

Python example

world.SendPush("go north")

VBscript example

world.SendPush "go north"

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SendPush)


SendSpecial

Script function

world.SendSpecial

 Read about scripting

Type

Method

Summary

Sends a message to the MUD with various options

Prototype

long SendSpecial(BSTR Message, BOOL Echo, BOOL Queue, BOOL Log, BOOL History);

 View list of data type meanings

Description

This sends the specified text to the world. It is like typing it into the command window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines.

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

* If "echo" is true, the command will be echoed in the output window.

* If "queue" is true, the command will be queued (after any other pending commands), otherwise it will be sent immediately

* If "log" is true, the command will be logged to the log file, if one is open, and logging commands is enabled.

* If "history" is true the command will be added to the command history buffer.

Return value

eWorldClosed : The world is closed

eItemInUse : Cannot be called from within OnPluginSent script callback

eOK: Sent OK

 View list of return code meanings

Lua example

SendPush ("go north", true, false, true, false)

Lua notes

The boolean arguments are optional and default to false.

Jscript example

world.SendSpecial ("go north", true, false, false, true);

VBscript example

world.SendSpecial "go north", vbTrue, vbFalse, vbFalse, vbTrue

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 LogSend (Sends a message to the MUD and logs it)

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SetCommand (Sends text to the command window)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SendSpecial)


SendToNotepad

Script function

world.SendToNotepad

 Read about scripting

Type

Method

Summary

Creates a notepad and sends text to it

Prototype

boolean SendToNotepad(BSTR Title, BSTR Contents);

 View list of data type meanings

Description

Creates a notepad window with the nominated title and contents.

The contents are copied "as is" without a trailing newline. If you want a newline you will need to add it yourself. The built-in constant "vbcrlf" can be used for this purpose in Visual Basic.

Return value

0: Window not created.

1:  Window created OK

Lua example

SendToNotepad ("Nick's window",

               "Hello, world\r\nanother line")

Lua notes

You can supply multiple arguments after the notepad name, which are concatenated together.

Jscript example

world.SendToNotepad("Nick's window",

                    "Hello, world\r\nanother line")

PerlScript example

$world->SendToNotepad("Nick's window",

                  "Hello, world\r\nanother line");

Python example

world.SendToNotepad("Nick's window",

                    "Hello, world\r\nanother line")

VBscript example

world.SendToNotepad "Nick's window", "Hello, world" & _

              vbcrlf & "another line"

See Also ...

Topic

 Notepad

Functions

 ActivateNotepad (Activates a notepad window)

 AppendToNotepad (Appends text to a notepad window)

 CloseNotepad (Closes a notepad window)

 GetNotepadLength (Gets the length of the text in a notepad window)

 GetNotepadList (Gets the list of open notepads - returning their titles)

 GetNotepadText (Gets the text from a notepad window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 NotepadColour (Changes the text and background colour of the selected notepad window)

 NotepadFont (Changes the font and style of the selected notepad window)

 NotepadReadOnly (Make a selected notepad window read-only)

 NotepadSaveMethod (Changes the save method for this notepad window)

 ReplaceNotepad (Replaces text in a notepad window)

 SaveNotepad (Saves a notepad window to disk)

(Help topic: function=SendToNotepad)


SetAliasOption

Script function

world.SetAliasOption

 Read about scripting

Type

Method

Summary

Sets the value of a named alias option

Prototype

long SetAliasOption(BSTR AliasName, BSTR OptionName, BSTR Value);

 View list of data type meanings

Description

Sets the current value of an alias option.

You must specify the name of an existing alias, and an alias option from the list given for GetAliasOption. These are the same names as used in the XML world files for alias options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing aliases copied to the clipboard or in world files and plugins. You already know the name when getting the alias option (it is AliasName), and this function is provided to modify existing aliases, not rename them. To change the name of an alias use ExportXML, modify the XML, and then ImportXML.

If SetAliasOption is called from within a plugin, the aliases for the current plugin are used, not the "global" MUSHclient aliases.

For numeric options (such as "sequence") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true

"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

The various option names are:

"echo_alias":               y/n - echo alias itself to output window

"enabled":                  y/n - alias is enabled

"expand_variables":         y/n - expand variables (like @target)

"group":                    (string - group name)

"ignore_case":              y/n - caseless matching

"keep_evaluating":          y/n - evaluate next alias in sequence

"match":                    (string - what to match)

"menu":                     y/n - add alias to menu that appears if you LH click

"omit_from_command_history":   y/n - omit alias from the command history

"omit_from_log":            y/n - omit alias from log file

"omit_from_output":         y/n - omit sent text from the output window

"one_shot":                 y/n - alias is deleted after firing

"regexp":                   y/n - regular expression

"script":                   (string - name of function to call)

"send":                     (multi-line string - what to send)

"send_to":                  0 - 13 - "send to" location (see below)

"sequence":                 0 - 10000 - sequence number in which to check - lower first

"user":                     -2147483647 to 2147483647 - user-defined number

"variable":                 (string - name of variable to send to)

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Return value

eInvalidObjectLabel: The alias name is not valid

eAliasCannotBeEmpty: The "match_text" cannot be empty

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)

eOK: set OK

 View list of return code meanings

Lua example

SetAliasOption ("myalias", "match", "north")

Lua notes

The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

You can use true, false or nil for boolean options.

Jscript example

world.SetAliasOption ("myalias", "match", "north");

PerlScript example

$world->SetAliasOption ("myalias", "match", "north");

Python example

world.SetAliasOption ("myalias", "match", "north")

VBscript example

world.SetAliasOption "myalias", "match", "north"

See Also ...

Topics

 Aliases

 Auto-mapper

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Keypad navigation

 Macro keys

 Plugins

 Regular Expressions

 Speed walking

 Timers

 Triggers

Functions

 AddAlias (Adds an alias)

 DeleteAlias (Deletes an alias)

 DeleteAliasGroup (Deletes a group of aliases)

 DeleteTemporaryAliases (Deletes all temporary aliases)

 EnableAlias (Enables or disables an alias)

 EnableAliasGroup (Enables/disables a group of aliases)

 GetAlias (Gets details about an alias)

 GetAliasInfo (Gets details about an alias)

 GetAliasList (Gets the list of aliases)

 GetAliasOption (Gets the value of a named alias option)

 GetAliasWildcard (Returns the contents of the specified wildcard for the named alias)

 GetPluginAliasInfo (Gets details about a named alias for a specified plugin)

 GetPluginAliasList (Gets the list of aliases in a specified plugin)

 GetPluginAliasOption (Gets the value of a named alias option for a specified plugin)

 IsAlias (Tests to see if an alias exists)

(Help topic: function=SetAliasOption)


SetAlphaOption

Script function

world.SetAlphaOption

 Read about scripting

Type

Method

Summary

Sets value of a named world alphanumeric option

Prototype

long SetAlphaOption(BSTR OptionName, BSTR Value);

 View list of data type meanings

Description

Sets the value of a world alphanumeric (string) option.

You can use GetAlphaOptionList to get a list of the names of all possible options.

Use SetOption to set numeric and boolean options.

Return value

eUnknownOption - option name not recognised

eOK - set OK

 View list of return code meanings

Lua example

SetAlphaOption ("player", "Gandalf")

Jscript example

world.setalphaoption ("player", "Gandalf");

PerlScript example

$world->setalphaoption ("player", "Gandalf");

Python example

world.setalphaoption ("player", "Gandalf")

VBscript example

world.setalphaoption "player", "Gandalf"

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetInfo (Gets information about the current world)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=SetAlphaOption)


SetBackgroundColour

Script function

world.SetBackgroundColour

 Read about scripting

Type

Method

Summary

Sets a background colour for the output window

Prototype

long SetBackgroundColour(long Colour);

 View list of data type meanings

Description

This changes the default background colour of the output window. This is intended to be used to make "mood" changes to the output window. For example, if you are currently playing in a watery zone, the background colour could change from black to a deep blue.

You simply specify the RGB code for the desired colour, or the constant 0xFFFFFFFF to indicate to use the default behaviour. Normally MUSHclient draws the background in ANSI colour "normal black". If you have set a colour, then any time the background colour for text would have been "normal black", then the background is not drawn and thus the background colour you chose is allowed to stay.

This function cannot fail, and returns the previous background colour.

Return value

The RGB colour which was the previous background colour.

Lua example

SetBackgroundColour (0x000055)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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=SetBackgroundColour)


SetBackgroundImage

Script function

world.SetBackgroundImage

 Read about scripting

Type

Method

Summary

Sets a background image for the output window

Prototype

long SetBackgroundImage(BSTR FileName, short Mode);

 View list of data type meanings

Description

This sets a background image for output window. The text in the output window is drawn on top of this. If the image does not completely fill the window, the background colour is visible beneath it.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type.  The file name can be the empty string (ie. "") in which case any existing image will be removed.

Mode - a number indicating where you want the image positioned on the screen. Whenever the screen is resized or redrawn the contents of the image are drawn in the requested position:

0 = strech to output view size

1 = stretch with aspect ratio

2 = strech to owner size

3 = stretch with aspect ratio

4 = top left

5 = center left-right at top

6 = top right

7 = on right, center top-bottom

8 = on right, at bottom

9 = center left-right at bottom

10 = on left, at bottom

11 = on left, center top-bottom

12 = centre all

13 = tile

The "stretch" versions expand or contract the image to fit the output window. If you use "with aspect ratio" the image fits exactly top-to-bottom, and may be clipped left-right to preserve the original aspect ratio.

The difference beteween "output view" and "owner size" is that with "output view" (modes 0 and 1) the image will tend to flicker annoyingly if you have automatic resizing of the command window active (as this will make the output window size change, and thus the image size will keep changing) .

Return value

eBadParameter: Mode out of range above, or file name less than 5 characters, or file name does not end in .BMP or .PNG

eFileNotFound: File not found

eCouldNotOpenFile: File could not be loaded (perhaps corrupt)

eOK: Success

 View list of return code meanings

Lua example

SetBackgroundImage ("wolf.bmp", 0)

Lua notes

You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0

miniwin.pos_stretch_to_view_with_aspect = 1

miniwin.pos_stretch_to_owner = 2

miniwin.pos_stretch_to_owner_with_aspect = 3

miniwin.pos_top_left = 4

miniwin.pos_top_center = 5

miniwin.pos_top_right = 6

miniwin.pos_center_right = 7

miniwin.pos_bottom_right = 8

miniwin.pos_bottom_center = 9

miniwin.pos_bottom_left = 10

miniwin.pos_center_left = 11

miniwin.pos_center_all = 12

miniwin.pos_tile = 13

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 SetBackgroundColour (Sets a background colour 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)

 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=SetBackgroundImage)


SetChanged

Script function

world.SetChanged

 Read about scripting

Type

Method

Summary

Sets or clears the "document has changed" flag

Prototype

void SetChanged(BOOL ChangedFlag);

 View list of data type meanings

Description

Use this function to set or clear the "world has changed" flag. If this flag is set, you will be asked to save it. If clear, you will not be asked to save it.

Return value

Nothing.

Lua example

SetChanged (true)

Lua notes

The argument is optional, and defaults to true.

Jscript example

SetChanged (true)

VBscript example

SetChanged vbTrue

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=SetChanged)


SetChatOption

Script function

world.SetChatOption

 Read about scripting

Type

Method

Summary

Sets the value of a chat session option

Prototype

long SetChatOption(long ID, BSTR OptionName, BSTR Value);

 View list of data type meanings

Description

Sets the current value of a chat session option.

You must specify the identifier of a current chat session, and a chat option from the list described for the routine GetChatOption.

For numeric options (such as the flags) the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9).

For boolean options (such as "ignore") the supplied string may be:

"y", "Y", or "1" for true

"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

Note that because chat sessions are transitory the option is not remembered in the world file or anywhere else for future sessions. Thus, any options must be set on a per-session basis.

See the supplied Chat.xml plugin for an example of how you can do that automatically as a new session is started.

Return value

eChatIDNotFound: That chat ID is not a current chat session.

eOptionOutOfRange: The numeric option is out of range.

ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)

eUnknownOption: Option name is not known.

eOK: Set the option OK.

 View list of return code meanings

Lua example

SetChatOption (ChatGetID ("nick"), "group", "friends")

Lua notes

You can use true or false for boolean options, as these are converted to 1 or 0.

Jscript example

SetChatOption (ChatGetID ("nick"), "group", "friends");

PerlScript example

SetChatOption (ChatGetID ("nick"), "group", "friends");

Python example

world.SetChatOption (world.ChatGetID ("nick"), "group", "friends")

VBscript example

SetChatOption ChatGetID ("nick"), "group", "friends"

See Also ...

Topics

 Chat system

 Getting started

Functions

 ChatAcceptCalls (Accepts incoming chat calls)

 ChatCall (Calls a chat server (makes an outgoing call) using the MudMaster chat protocol)

 ChatCallzChat (Calls a zChat chat server (makes an outgoing call))

 ChatDisconnect (Disconnects a current chat call)

 ChatDisconnectAll (Disconnects all current chat calls)

 ChatEverybody (Sends a chat message to every connected chat user)

 ChatGetID (Looks up what chat ID (identifier) corresponds to a particular chat name)

 ChatGroup (Sends a chat message to every connected chat user in the specified group)

 ChatID (Sends a chat message to a particular chat session)

 ChatMessage (Sends a message to a chat user (raw format))

 ChatNameChange (Changes your chat name)

 ChatNote (Does a note using ANSI codes for the chat system)

 ChatPasteEverybody (Pastes the clipboard contents to every connected person)

 ChatPasteText (Pastes the clipboard contents to that person)

 ChatPeekConnections (Sends a "peek connections" message to the specified chat user)

 ChatPersonal (Sends a chat message to a particular person)

 ChatPing (Sends a ping message to the specified chat user)

 ChatRequestConnections (Sends a "request connections" message to the specified chat user)

 ChatSendFile (Starts sending a file to the specified chat user)

 ChatStopAcceptingCalls (Stops this world from accepting chat calls)

 ChatStopFileTransfer (Stops a file transfer in progress to that chat user)

 GetChatInfo (Get information about a chat connection)

 GetChatList (Gets the list of chat sessions)

 GetChatOption (Gets the value of a chat session option)

(Help topic: function=SetChatOption)


SetClipboard

Script function

world.SetClipboard

 Read about scripting

Type

Method

Summary

Sets the clipboard contents

Prototype

void SetClipboard(BSTR Text);

 View list of data type meanings

Description

Sets the Windows clipboard to the supplied string.

Return value

Nothing.

Lua example

SetClipboard ("hello, world")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

SetClipboard ("hello, world");

VBscript example

SetClipboard "hello, world"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 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=SetClipboard)


SetCommand

Script function

world.SetCommand

 Read about scripting

Type

Method

Summary

Sends text to the command window

Prototype

long SetCommand(BSTR Message);

 View list of data type meanings

Description

This lets you send text to the command window. It will only act if the command window is currently empty (to avoid wiping out something you are typing).

Because of this you cannot test "setcommand" by typing it into the command window, because by definition, the command window will not be empty (it will have the "setcommand" in it). You must do it from a script, or an immediate window.

Return value

eCommandNotEmpty : Command area was not empty

eOK: Set OK

 View list of return code meanings

Lua example

SetCommand ("think Here is another command")

Jscript example

world.SetCommand("think Here is another command");

PerlScript example

$world->SetCommand("think Here is another command");

Python example

world.SetCommand("think Here is another command")

VBscript example

world.SetCommand "think Here is another command"

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommandSelection (Selects specified columns in the command window)

(Help topic: function=SetCommand)


SetCommandSelection

Script function

world.SetCommandSelection

 Read about scripting

Type

Method

Summary

Selects specified columns in the command window

Prototype

long SetCommandSelection(long First, long Last);

 View list of data type meanings

Description

Lets you select text in the command window. This is intended for specialized applications like a spell checker where, after finding a spelling mistake, you select the misspelt word.

First - the first character to select (1-relative), so the first character is 1.

If "First" is zero, then any selection is removed.

Last - the last character to select (1-relative).

If "Last" is -1 then the rest of the line is selected.

Thus, to select everything, make First = 1 and Last = -1.

To put the cursor between characters, specify them backwards. See the example below.

Examples:

SetCommandSelection (2, 4) --> select characters 2 to 4

SetCommandSelection (0, 0) --> select nothing

SetCommandSelection (1, -1) --> select everything

SetCommandSelection (10, -1) --> select column 10 onwards

SetCommandSelection (6, 5) --> put the cursor between column 5 and column 6

If you want to *get* the current selection in the command window, use GetInfo(236) (first character) and GetInfo(237) (last character).

Return value

eOK: Set OK

 View list of return code meanings

Lua example

SetCommandSelection (2, 4)

Jscript example

world.SetCommandSelection (2, 4);

PerlScript example

$world->SetCommandSelection (2, 4);

Python example

world.SetCommandSelection (2, 4)

VBscript example

SetCommandSelection 2, 4

See Also ...

Topics

 Commented softcode

 Sending to the world

Functions

 Note (Sends a note to the output window)

 PasteCommand (Pastes text into the command window, replacing the current selection)

 Send (Sends a message to the MUD)

 SendImmediate (Sends a message to the MUD immediately, bypassing the speedwalk queue)

 SendNoEcho (Sends a message to the MUD without echoing in the output window)

 SendPkt (Sends a low-level packet of data to the MUD)

 SendPush (Sends a message to the MUD and saves it in the command history buffer)

 SendSpecial (Sends a message to the MUD with various options)

 SetCommand (Sends text to the command window)

(Help topic: function=SetCommandSelection)


SetCommandWindowHeight

Script function

world.SetCommandWindowHeight

 Read about scripting

Type

Method

Summary

Set the height of the command (input) window

Prototype

long SetCommandWindowHeight(short Height);

 View list of data type meanings

Description

Sets the height of the command window in pixels.

Return value

eBadParameter: Specified height is < 0 or such that the output window would be < 20 pixels high.

eOK: Completed OK

 View list of return code meanings

Lua example

SetCommandWindowHeight (15)  -- enough for a line

SetCommandWindowHeight  (0)  -- not visible

Jscript example

SetCommandWindowHeight (15)  // enough for a line

SetCommandWindowHeight  (0)  // not visible

VBscript example

SetCommandWindowHeight 15  ' enough for a line

SetCommandWindowHeight 0    ' not visible

See Also ...

Functions

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 MoveMainWindow (Move and resize the main MUSHclient window)

 MoveNotepadWindow (Move and resize the specified notepad window)

 MoveWorldWindow (Move and resize a world window)

 MoveWorldWindowX (Move and resize a specific world window)

 SetWorldWindowStatus (Sets the scroll bar position, and hides or shows it)

(Help topic: function=SetCommandWindowHeight)


SetCursor

Script function

world.SetCursor

 Read about scripting

Type

Method

Summary

Changes the shape of the mouse cursor

Prototype

long SetCursor(long Cursor);

 View list of data type meanings

Description

This function lets you change the shape of the cursor during a hotspot drag operation.

The argument a number which indicates what shape the mouse pointer is to take, as follows:

-1: no cursor

0: arrow

1: hand

2: I-beam

3: + symbol

4: wait (hour-glass)

5: up arrow

6: arrow nw-se

7: arrow ne-sw

8: arrow e-w

9: arrow n-s

10: arrow - all ways

11: (X) cannot do action

12: help (? symbol)

This operation is only effective when the mouse is "captured" - basically after a mouse-down but before the corresponding mouse-up. Otherwise the cursor is likely to be promptly restored by MUSHclient's cursor management code, for example to an I-beam cursor if it moves over text, or to the designated cursor if it moves over miniwindow hotspots.

Cursor shape -1 (no cursor) added in version 4.45.

Return value

eBadParameter - cursor value is not in the list above

eOK - completed OK

 View list of return code meanings

Lua example

SetCursor (11)  -- make an X cursor

Lua notes

You can use the following constants for the cursor:

miniwin.cursor_none = -1

miniwin.cursor_arrow = 0

miniwin.cursor_hand = 1

miniwin.cursor_ibeam = 2

miniwin.cursor_plus = 3

miniwin.cursor_wait = 4

miniwin.cursor_up = 5

miniwin.cursor_nw_se_arrow = 6

miniwin.cursor_ne_sw_arrow = 7

miniwin.cursor_ew_arrow = 8

miniwin.cursor_ns_arrow = 9

miniwin.cursor_both_arrow = 10

miniwin.cursor_x = 11

miniwin.cursor_help = 12

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=SetCursor)


SetCustomColourName

Script function

world.SetCustomColourName

 Read about scripting

Type

Method

Summary

Sets the name of a custom colour

Prototype

long SetCustomColourName(short WhichColour, BSTR Name);

 View list of data type meanings

Description

Use this to set the name of one of the 16 custom colours in the world's custom colour configuration.

You must specify *which* colour you want to get/set, in the range 1 to 16.

The name can be any string, which must be from 1 to 30 characters long.

Return value

eOK - colour name set OK

eOptionOutOfRange - custom colour number out of the range 1 to 16

eNoNameSpecified - name was empty

eInvalidObjectLabel - name was more than 30 characters long

 View list of return code meanings

Lua example

SetCustomColourName (5, "combat")

Jscript example

SetCustomColourName(5, "combat");

PerlScript example

$world->SetCustomColourName (5, "combat");

Python example

world.SetCustomColourName (5, "combat")

VBscript example

SetCustomColourName(5, "combat")

See Also ...

Topics

 Colour management

 Default triggers/aliases/timers/macros/colours

Functions

 AdjustColour (Adjust an RGB colour)

 ANSI (Generates an ANSI colour sequence)

 BoldColour (Gets/sets the RGB colour for one of the 8 ANSI bold colours)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 CustomColourBackground (Sets the RGB value for the background of a custom colour)

 CustomColourText (Sets the RGB value for the text of a custom colour)

 GetCustomColourName (Gets the name of a custom colour)

 GetMapColour (Returns the mapping for how a particular colour will be displayed)

 MapColour (Changes the colour mapping - the way colours are displayed)

 MapColourList (Returns an array of all the mapped colours)

 NormalColour (Gets/sets the RGB colour for one of the 8 ANSI normal colours)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 PickColour (Invokes the MUSHclient colour picker dialog)

 RGBColourToName (Converts an RGB colour code to its equivalent name)

(Help topic: function=SetCustomColourName)


SetEntity

Script function

world.SetEntity

 Read about scripting

Type

Method

Summary

Sets the value of an MXP entity

Prototype

void SetEntity(BSTR Name, BSTR Contents);

 View list of data type meanings

Description

Sets the value of an MXP (custom) entity.

If the supplied contents is the empty string, the entity is deleted.

If the entity already exists it is replaced.

No checking is made for the name or contents strings' values (for example, they might be just spaces).

It is up to you to use sensible values.

Custom entities are stored separately from standard entities. Thus you cannot replace, for example, the "lt" entity.

Return value

Nothing.

Lua example

SetEntity ("foo", "bar)

Lua notes

The contents are optional. If omitted they default to the empty string, and thus the named entity will be deleted.

Jscript example

SetEntity ("foo", "bar");

VBscript example

SetEntity "foo", "bar"

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetVariable (Gets the contents of a variable)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetVariable (Sets the value of a variable)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=SetEntity)


SetForegroundImage

Script function

world.SetForegroundImage

 Read about scripting

Type

Method

Summary

Sets a foreground image for the output window

Prototype

long SetForegroundImage(BSTR FileName, short Mode);

 View list of data type meanings

Description

This sets a foreground image for output window. The text in the output window is drawn under this.

With "stretching" or "tiling" modes, the text from the MUD will not be visible.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type. The file name can be the empty string (ie. "") in which case any existing image will be removed.

Mode - a number indicating where you want the image positioned on the screen. Whenever the screen is resized or redrawn the contents of the image are drawn in the requested position:

0 = strech to output view size

1 = stretch with aspect ratio

2 = strech to owner size

3 = stretch with aspect ratio

4 = top left

5 = center left-right at top

6 = top right

7 = on right, center top-bottom

8 = on right, at bottom

9 = center left-right at bottom

10 = on left, at bottom

11 = on left, center top-bottom

12 = centre all

13 = tile

The "stretch" versions expand or contract the image to fit the output window. If you use "with aspect ratio" the image fits exactly top-to-bottom, and may be clipped left-right to preserve the original aspect ratio.

The difference beteween "output view" and "owner size" is that with "output view" (modes 0 and 1) the image will tend to flicker annoyingly if you have automatic resizing of the command window active (as this will make the output window size change, and thus the image size will keep changing) .

Return value

eBadParameter: Mode out of range above, or file name less than 5 characters, or file name does not end in .BMP or .PNG

eFileNotFound: File not found

eCouldNotOpenFile: File could not be loaded (perhaps corrupt)

eOK: Success

 View list of return code meanings

Lua example

SetForegroundImage ("wolf.bmp", 0)

Lua notes

You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0

miniwin.pos_stretch_to_view_with_aspect = 1

miniwin.pos_stretch_to_owner = 2

miniwin.pos_stretch_to_owner_with_aspect = 3

miniwin.pos_top_left = 4

miniwin.pos_top_center = 5

miniwin.pos_top_right = 6

miniwin.pos_center_right = 7

miniwin.pos_bottom_right = 8

miniwin.pos_bottom_center = 9

miniwin.pos_bottom_left = 10

miniwin.pos_center_left = 11

miniwin.pos_center_all = 12

miniwin.pos_tile = 13

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetMainTitle (Sets the main output window title)

 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=SetForegroundImage)


SetInputFont

Script function

world.SetInputFont

 Read about scripting

Type

Method

Summary

Sets the font for the input window

Prototype

void SetInputFont(BSTR FontName, short PointSize, short Weight, boolean Italic);

 View list of data type meanings

Description

Use this to change the command window font. The *entire* window font changes, you cannot change individual lines or words.

Also see SetOutputFont.

The weight can be one of:

 (Don't Care) 0

 Thin 100

 Extralight 200

 Light 300

 Normal 400

 Medium 500

 Semibold 600

 Bold 700

 Extrabold 800

 Heavy 900

 Italic can be true or false.

Return value

Nothing.

Lua example

SetInputFont("Lucida Console", 15, 400, 0)

Lua notes

The Italic flag is optional, and defaults to false.

Jscript example

world.SetInputFont("Lucida Console", 15, 400, 0);

PerlScript example

$world->SetInputFont("Lucida Console", 15, 400, 0);

Python example

world.SetInputFont("Lucida Console", 15, 400, 0)

VBscript example

world.SetInputFont "Lucida Console", 15, 400, 0

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetOption (Sets value of a named world option)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=SetInputFont)


SetMainTitle

Script function

world.SetMainTitle

 Read about scripting

Type

Method

Summary

Sets the main output window title

Prototype

void SetMainTitle(BSTR Title);

 View list of data type meanings

Description

This sets the window title (for the whole client window) to the nominated text. You could use this to make the tile reflect the character name, world name, or whatever you want.

Setting the title to an empty string (ie. "") will revert back to the default title line (the world name, plus connection status).

Return value

Nothing.

Lua example

SetMainTitle "TinyMUX - admin login"

Lua notes

You can supply multiple arguments, which are concatenated together.

VBscript example

SetMainTitle "TinyMUX - admin login"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 Note (Sends a note to the output window)

 PlaySound (Plays a sound using DirectSound)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 Send (Sends a message to the MUD)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommand (Sends text to the command window)

 SetForegroundImage (Sets a foreground image for 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=SetMainTitle)


SetNotes

Script function

world.SetNotes

 Read about scripting

Type

Method

Summary

Sets the notes for the world.

Prototype

void SetNotes(BSTR Message);

 View list of data type meanings

Description

This sets the notes for the current world.

Use the built-in constant "vbcrlf" to add a new line to the notes.

Use GetNotes if you want to get the existing notes (perhaps to append to them, as in the example).

Return value

Nothing.

Lua example

SetNotes (GetNotes () ..

          "\r\nThis is a new line of notes")

Jscript example

world.setnotes(world.getnotes() +

     "\r\nThis is a new line of notes");

PerlScript example

$world->setnotes($world->getnotes() .

     "\r\nThis is a new line of notes");

Python example

world.setnotes(world.getnotes +

     "\r\nThis is a new line of notes")

VBscript example

world.setnotes world.getnotes & vbcrlf _

     & "This is a new line of notes"

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNotes (Gets the world's notes)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 Tell (Sends a message to the output window - not terminated by a newline)

(Help topic: function=SetNotes)


SetOption

Script function

world.SetOption

 Read about scripting

Type

Method

Summary

Sets value of a named world option

Prototype

long SetOption(BSTR OptionName, long Value);

 View list of data type meanings

Description

Sets value of a world option. Many options are booleans (true or false).

For boolean options the supplied value may be:

1 for true

0 for false

Also if you are using Lua you can supply simply true or false.

You can use GetOptionList to get a list of the names of all possible options.

Use SetAlphaOption to set alphanumeric options.

Return value

eUnknownOption - option name not recognised

eOptionOutOfRange - option value out of range

ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)

eOK - set OK

 View list of return code meanings

Lua example

SetOption ("show_italic", 1)

Lua notes

You can use true, false or nil for boolean options.

Jscript example

world.setoption ("show_italic", 1);

PerlScript example

$world->setoption ("show_italic", 1);

Python example

world.setoption ("show_italic", 1)

VBscript example

world.setoption "show_italic", 1

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOutputFont (Sets the font for the output window.)

(Help topic: function=SetOption)


SetOutputFont

Script function

world.SetOutputFont

 Read about scripting

Type

Method

Summary

Sets the font for the output window.

Prototype

void SetOutputFont(BSTR FontName, short PointSize);

 View list of data type meanings

Description

Use this to change the output font. The *entire* window font changes, you cannot change individual lines or words.

Also see SetInputFont.

Return value

Nothing.

Lua example

SetOutputFont ("Lucida Console", 9)

Jscript example

world.SetOutputFont("Lucida Console", 9);

PerlScript example

$world->SetOutputFont("Lucida Console", 9);

Python example

world.SetOutputFont("Lucida Console", 9)

VBscript example

world.SetOutputFont "Lucida Console", 9

See Also ...

Topic

 Option setting and retrieval

Functions

 GetAlphaOption (Gets the value of an alphanumeric configuration option)

 GetAlphaOptionList (Gets the list of world alphanumeric options)

 GetCurrentValue (Gets the current value of a named world option)

 GetDefaultValue (Gets the default value of a named world option)

 GetGlobalOption (Gets the value of a global configuration option)

 GetGlobalOptionList (Gets the list of global options)

 GetLoadedValue (Gets value of a named world option, as loaded from the world file)

 GetOption (Gets value of a named world option)

 GetOptionList (Gets the list of world options)

 SetAlphaOption (Sets value of a named world alphanumeric option)

 SetInputFont (Sets the font for the input window)

 SetOption (Sets value of a named world option)

(Help topic: function=SetOutputFont)


SetScroll

Script function

world.SetScroll

 Read about scripting

Type

Method

Summary

Sets the scroll bar position, and hides or shows it

Prototype

long SetScroll(long Position, BOOL Visible);

 View list of data type meanings

Description

This lets you do two things:

    * Hide the existing scroll bar if desired

    * Set the "scroll position" in the output window

The first feature (hiding the scroll bar) lets you, well, hide it, so that you can draw your own wherever you want (eg. with a themed miniwindow somewhere near where the text appears).

The second feature lets your code scroll the text around (so you can still use the existing output buffer) in response to the player clicking and dragging on "your" thumb, or arrows.

A position of -1 means "the end of the window" (which is the number of lines multiplied by the size of the font, less the size of the output window).

A position of -2 means "no change".

You can use GetInfo (296) to find the current scroll-bar position (and thus add or subtract from it, to scroll up or down small amounts (like a line or a page).

You can use GetInfo (120) to find if the scroll-bar is currently hidden or not.

The existing code adds the font height (GetInfo (212)) to the current scroll position to scroll downwards a line, and subtracts it to scroll up a line.

To scroll up or down pages you need to find the size of the output window text rectangle, and add or subtract that.

Return value

eOK - success

 View list of return code meanings

Lua example

SetScroll (0, false)  -- hide scroll bar, go to top of window

SetScroll (-1, false) -- hide scroll bar, go to end of window

SetScroll (-2, false) -- hide scroll bar, do not change position

SetScroll (-2, true)  -- show scroll bar, do not change position

Lua notes

The Visible flag is optional and defaults to true.

See Also ...

Function

 GetInfo (Gets information about the current world)

(Help topic: function=SetScroll)


SetStatus

Script function

world.SetStatus

 Read about scripting

Type

Method

Summary

Sets the status line text

Prototype

void SetStatus(BSTR Message);

 View list of data type meanings

Description

This sets the status line (at the bottom of the screen) to the nominated text. It is useful for keeping track of things. The status line is separately maintained for each world.

Return value

Nothing.

Lua example

SetStatus ("Current HP = ", GetVariable("hp"))

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.SetStatus("Current HP = " + world.GetVariable("hp"));

PerlScript example

$world->SetStatus("Current HP = " . $world->GetVariable("hp"));

Python example

world.SetStatus("Current HP = " + world.GetVariable("hp"))

VBscript example

world.setstatus "Current HP = " & Cstr (world.getvariable ("hp"))

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 Note (Sends a note to the output window)

 PlaySound (Plays a sound using DirectSound)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 Send (Sends a message to the MUD)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommand (Sends text to the command window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 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=SetStatus)


SetTimerOption

Script function

world.SetTimerOption

 Read about scripting

Type

Method

Summary

Sets the value of a named timer option

Prototype

long SetTimerOption(BSTR TimerName, BSTR OptionName, BSTR Value);

 View list of data type meanings

Description

Sets the current value of a timer option.

You must specify the name of an existing timer, and a timer option from the list given for GetTimerOption. These are the same names as used in the XML world files for timer options.

For a detailed description about the meanings of the fields, see AddTimer.

Note that you can neither get nor set the "name" field. It is listed below for completeness in viewing timers copied to the clipboard or in world files and plugins. You already know the name when getting the timer option (it is TimerName), and this function is provided to modify existing timers, not rename them. To change the name of a timer use ExportXML, modify the XML, and then ImportXML.

If SetTimerOption is called from within a plugin, the timers for the current plugin are used, not the "global" MUSHclient timers.

For numeric options (such as "hour") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true

"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

The "offset" options are the time offset within the interval. In other words, if the interval is an hour, but the offset is 45 minutes, then the timer fires 15 minutes into the hour (it still fires every hour, but 45 minutes is subtracted from the fire time). This lets you stagger timer fire times.

The various option names are:

"active_closed":            y/n - timer is active when world closed

"at_time":                  y/n - y=fire *at* time of day, otherwise every interval

"enabled":                  y/n - timer is enabled

"group":                    (string - group name)

"hour":                     hour to fire at (or every hour)

"minute":                   minute to fire at (or every minute)

"offset_hour":              offset hour - fire at time *plus* this

"offset_minute":            offset minute - fire at time *plus* this

"offset_second":            offset second - fire at time *plus* this

"omit_from_log":            y/n - omit timer from log file

"omit_from_output":         y/n - omit timer output from log file

"one_shot":                 y/n - delete after firing

"script":                   (string - name of function to call)

"second":                   second to fire at (or every second)

"send":                     (multi-line string - what to send)

"send_to":                  0 - 13 - "send to" location (see below)

"user":                      -2147483647 to 2147483647 - user-defined number

"variable":                 (string - name of variable to send to)

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Return value

eInvalidObjectLabel: The timer name is not valid

eTimeInvalid: Time is out of range (hours not 0 to 23, minutes/seconds not 0-59)

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)

eOK: set OK

 View list of return code meanings

Lua example

SetTimerOption ("mytimer", "minute", "5")

Lua notes

The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

You can use true, false or nil for boolean options.

Jscript example

world.SetTimerOption ("mytimer", "minute", "5");

PerlScript example

$world->SetTimerOption ("mytimer", "minute", "5");

Python example

world.SetTimerOption ("mytimer", "minute", "5")

VBscript example

world.SetTimerOption "mytimer", "minute", "5"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Timers

 Triggers

Functions

 AddTimer (Adds a timer)

 DeleteTemporaryTimers (Deletes all temporary timers)

 DeleteTimer (Deletes a timer)

 DeleteTimerGroup (Deletes a group of timers)

 DoAfter (Adds a one-shot, temporary timer - simplified interface)

 DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)

 DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)

 EnableTimer (Enables or disables an timer)

 EnableTimerGroup (Enables/disables a group of timers)

 GetPluginTimerOption (Gets the value of a named timer option for a specified plugin)

 GetPluginTriggerOption (Gets the value of a named trigger option for a specified plugin)

 GetTimer (Gets details about a timer)

 GetTimerInfo (Gets details about a timer)

 GetTimerList (Gets the list of timers)

 GetTimerOption (Gets the value of a named timer option)

 IsTimer (Tests to see if a timer exists)

 ResetTimer (Resets a named timer)

 ResetTimers (Resets all timers)

(Help topic: function=SetTimerOption)


SetTitle

Script function

world.SetTitle

 Read about scripting

Type

Method

Summary

Sets the world window title

Prototype

void SetTitle(BSTR Title);

 View list of data type meanings

Description

This sets the window title (for the world window) to the nominated text. You could use this to make the tile reflect the character name, world name, or whatever you want.

Setting the title to an empty string (ie. "") will revert back to the default title line (the world name, plus connection status).

Return value

Nothing.

Lua example

SetTitle "TinyMUX - admin login"

Lua notes

You can supply multiple arguments, which are concatenated together.

VBscript example

SetTitle "TinyMUX - admin login"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 Note (Sends a note to the output window)

 PlaySound (Plays a sound using DirectSound)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 Send (Sends a message to the MUD)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommand (Sends text to the command window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 SetStatus (Sets the status line text)

 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=SetTitle)


SetToolBarPosition

Script function

world.SetToolBarPosition

 Read about scripting

Type

Method

Summary

Sets the position of the game toolbars on the screen.

Prototype

long SetToolBarPosition(short Which, BOOL Float, short Side, long Top, long Left);

 View list of data type meanings

Description

Moves the toolbars around to your liking. The intention is to allow newly-distributed copies of MUSHclient to configure themselves appropriately.

Which: which toolbar, as follows:

1: Main toolbar (with the New, Open, Save, Print icons).

2: Game toolbar (with buttons for Edit Trigger, Edit Alias, log, etc.)

3: Activity toolbar (which shows the numbers 1 to 10)

4: Info toolbar (which lets you display informational messages)

Float: true or false

If true, the toolbar floats as a small independent window.

If false, the toolbar is docked to one side of the main client frame window

Side: which side to dock to, as follows:

1: top side

2: bottom side

3: left side

4: right side

If the style is set to "Float" then only "top" or "left" are valid (1 or 3), in which case the floating window has its icons arranged vertically or horizontally.

Top: Y co-ordinate of the top-left corner of the toolbar in client co-ordinates

Left: X co-ordinate of the top-left corner of the toolbar in client co-ordinates

(eg. 0, 0 would be the top-left corner).

Sizes of toolbars are:

1: 26 pixels high, 265 wide

2: 26 pixels high, 478 wide

3: 26 pixels high, 234 wide

4: 21 pixels high, 1007 wide

To place them side-by-side, you need to allow room for each one. For example:

SetToolBarPosition (1, false, 1, 0, 0)    -- main toolbar

SetToolBarPosition (2, false, 1, 0, 264)  -- game toolbar next to it

SetToolBarPosition (3, true, 1, 30, 500)  -- float activity toolbar

Return value

eBadParameter: A parameter was of range.

eOK: Successfully completed

 View list of return code meanings

Lua example

SetToolBarPosition (1, false, 1, 0, 0)    -- main toolbar

SetToolBarPosition (2, false, 1, 0, 264)  -- game toolbar next to it

SetToolBarPosition (3, true, 1, 30, 500)  -- float activity toolbar

VBscript example

SetToolBarPosition 1, false, 1, 0, 0    ' main toolbar

SetToolBarPosition 2, false, 1, 0, 264  ' game toolbar next to it

SetToolBarPosition 3, true, 1, 30, 500  ' float activity toolbar

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 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)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 Hash (Produces a hash (checksum) of a specified piece of text)

 Help (Shows help for a script function, or a list of functions)

 ImportXML (Imports configuration data in XML format)

 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)

 MoveNotepadWindow (Move and resize the specified notepad 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)

 SetBackgroundColour (Sets a background colour for the output window)

 SetBackgroundImage (Sets a background image for the output window)

 SetClipboard (Sets the clipboard contents)

 SetCommandWindowHeight (Set the height of the command (input) window)

 SetForegroundImage (Sets a foreground image for the output window)

 SetMainTitle (Sets the main output window title)

 SetStatus (Sets the status line text)

 SetTitle (Sets the world window title)

 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=SetToolBarPosition)


SetTriggerOption

Script function

world.SetTriggerOption

 Read about scripting

Type

Method

Summary

Sets the value of a named trigger option

Prototype

long SetTriggerOption(BSTR TriggerName, BSTR OptionName, BSTR Value);

 View list of data type meanings

Description

Sets the current value of a trigger option.

You must specify the name of an existing trigger, and a trigger option from the list given for GetTriggerOption. These are the same names as used in the XML world files for trigger options.

Note that you can neither get or set the "name" field. It is listed below for completeness in viewing triggers copied to the clipboard or in world files and plugins. You already know the name when getting the trigger option (it is TriggerName), and this function is provided to modify existing triggers, not rename them. To change the name of a trigger use ExportXML, modify the XML, and then ImportXML.

If SetTriggerOption is called from within a plugin, the triggers for the current plugin are used, not the "global" MUSHclient triggers.

For numeric options (such as "sequence") the supplied string will be converted to a number. It is an error if the string does not consist of digits (0 to 9). For the "user" option an optional leading sign is accepted.

For boolean options (such as "enabled") the supplied string may be:

"y", "Y", or "1" for true

"n", "N", or "0" for false

Also if you are using Lua you can supply simply true or false.

The various option names are:

"clipboard_arg":             0 - 10 - which wildcard to copy to the clipboard

"colour_change_type":        0=both, 1=foreground, 2=background

"custom_colour":             0=no change, 1 - 16, 17=other

"enabled":                   y/n - trigger is enabled

"expand_variables":          y/n - expand variables (like @target)

"group":                     (string - group name)

"ignore_case":               y/n - caseless matching

"inverse":                   y/n - only match if inverse, however see match_inverse

"italic":                    y/n - only match if italic, however see match_italic

"keep_evaluating":           y/n - evaluate next trigger in sequence

"lines_to_match":            0 - 200 - how many lines to match for multi-line triggers

"lowercase_wildcard":        y/n - make matching wildcards lower-case

"match":                     (string - what to match)

"match_style":      (see below) - what style and colour combination to match on

"multi_line":                y/n - multi-line trigger

"new_style":       (style(s) to change to: (bold (1) / underline (2) / italic (4) ) )

"omit_from_log":             y/n - omit matching line from log file

"omit_from_output":          y/n - omit matching line from output window

"one_shot":                  y/n - trigger is deleted after firing

"other_back_colour":         (number - RGB code of colour to change to)

"other_text_colour":         (number - RGB code of colour to change to)

"regexp":                    y/n - regular expression

"repeat":                    y/n - repeatedly evaluate on same line

"script":                    (string - name of function to call)

"send":                      (multi-line string - what to send)

"send_to":                   0 - 14 - "send to" location (see below)

"sequence":                  0 - 10000 - sequence in which to check - lower first

"sound":                     (string - sound file name to play)

"sound_if_inactive":         y/n - play sound even if world inactive

"user":                      -2147483647 to 2147483647 - user-defined number

"variable":                  (string - name of variable to send to)

Options that match on colour, bold, inverse or underline are tested against the first matching character.

Send-to locations

"0"    - send to MUD

"1"    - put in command window

"2"    - display in output window

"3"    - put in status line

"4"    - new notepad

"5"    - append to notepad

"6"    - put in log file

"7"    - replace notepad

"8"    - queue it

"9"    - set a variable

"10"    - re-parse as command

"11"    - send to MUD as speedwalk

"12"    - send to script engine

"13"    - send without queuing

"14"    - send to script engine - after omitting from output

Trigger match_style field will be as follows (in hex nibbles):

TBFS

T = what style to test

B = background colour

F = foreground colour

S = what style bits are wanted

Style bits:

NORMAL 0x0000 // normal text

HILITE 0x0001 // bold

UNDERLINE 0x0002 // underline

BLINK 0x0004 // italic (sent to client as blink)

INVERSE 0x0008 // need to invert it

MATCH_TEXT 0x0080 // match on text colour?

MATCH_BACK 0x0800 // match on background colour?

MATCH_HILITE 0x1000 // match on bold bit?

MATCH_UNDERLINE 0x2000 // match on underline?

MATCH_BLINK 0x4000 // match on blink?

MATCH_INVERSE 0x8000 // match on inverse?

Colours:

BLACK = 0

RED = 1

GREEN = 2

YELLOW = 3

BLUE = 4

MAGENTA = 5

CYAN = 6

WHITE = 7

See the forum posting at http://www.gammon.com.au/forum/?id=4873 for more details about match_style.

An easier way of settting trigger options, particularly ones relating to matching style and colours, could be to use ImportXML.

See the forum posting at http://www.gammon.com.au/forum/?id=7123 for more details about ImportXML, and the "addxml" module supplied for Lua scripting.

Return value

eInvalidObjectLabel: The trigger name is not valid

eTriggerCannotBeEmpty: The "match_text" cannot be empty

eScriptNameNotLocated: The script name cannot be located in the script file

eBadRegularExpression: The regular expression could not be evaluated

ePluginCannotSetOption: The option is marked as non-settable (in a plugin or not)

eOK: set OK

 View list of return code meanings

Lua example

SetTriggerOption ("mytrigger", "match", "north")

Lua notes

The "send_to" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0

sendto.command = 1

sendto.output = 2

sendto.status = 3

sendto.notepad = 4

sendto.notepadappend = 5

sendto.logfile = 6

sendto.notepadreplace = 7

sendto.commandqueue = 8

sendto.variable = 9

sendto.execute = 10

sendto.speedwalk = 11

sendto.script = 12

sendto.immediate = 13

sendto.scriptafteromit = 14

You can use true, false or nil for boolean options.

Jscript example

world.SetTriggerOption ("mytrigger", "match", "north");

PerlScript example

$world->SetTriggerOption ("mytrigger", "match", "north");

Python example

world.SetTriggerOption ("mytrigger", "match", "north")

VBscript example

world.SetTriggerOption "mytrigger", "match", "north"

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 StopEvaluatingTriggers (Stops trigger evaluation)

(Help topic: function=SetTriggerOption)


SetUnseenLines

Script function

world.SetUnseenLines

 Read about scripting

Type

Method

Summary

Sets the number of "unseen lines" for this world

Prototype

void SetUnseenLines(long Counter)

 View list of data type meanings

Description

Sets the number of "unseen lines" for this world's output window. The current number can be found by calling GetInfo (202).

This could be used in a trigger to make a certain type of line not "register" as new MUD output (for example, emotes about weather).

You could get the current number of unseen lines and subtract one, or just set the total number to zero.

Note that subtracting one might be safer, if there are already lines that are important preceding the uninteresting one.

If the uninteresting line is always followed by something else (like a prompt line) then you might need to subtract 2 from the count.

Return value

None.

Lua example

SetUnseenLines (0)  -- Make zero

SetUnseenLines (GetInfo (202) - 1)  -- Subtract one

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 SetStatus (Sets the status line text)

 SetTitle (Sets the world window title)

 SetToolBarPosition (Sets the position of the game toolbars on the screen.)

 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=SetUnseenLines)


SetVariable

Script function

world.SetVariable

 Read about scripting

Type

Method

Summary

Sets the value of a variable

Prototype

long SetVariable(BSTR VariableName, BSTR Contents);

 View list of data type meanings

Description

Sets the contents of a variable. If the named variable already exists the contents are replaced. If the variable doesn't exist it is created. Variables are contained in the "world" configuration, and saved when the world is saved. You can use variables to "remember" data from one session of MUSHclient to the next.

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)

b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

Please note that the following characters will not be handled correctly:

* The byte value hex 00 (otherwise known as 0x00 or null). This is used as a string terminator in MUSHclient, and attempts to imbed 0x00 values into variables will result in the variable being terminated at the 0x00 position.

* Carriage-return (hex 0D or 0x0D) and line-feeds (hex 0A or 0x0A). You can use these internally however you like, however when they are read from a plugin state file, or a MUSHclient world file, carriage returns are dropped, and line-feeds are converted to the sequence 0x0D 0x0A (carriage-return followed by linefeed). This is not normally a problem - because line breaks are usually stored as carriage-return/linefeed, and the reading process effectively will read them back in as that. However individual carriage-returns or linefeeds will not be read back in correctly.

If you are planning to use variables to store "binary" data - that is, data that can have all 256 possible character values, you are advised to convert them to base-64 encoded strings (using Base64Encode) when saving them, and conver them back (using Base64Decode) when loading them. Also be aware that only the Lua version of the base 64 encoding (utils.base64encode and utils.base64decode) will correctly handle the 0x00 value.

Return value

eInvalidObjectLabel: The variable name is not valid

eOK: The variable contents were set

 View list of return code meanings

Lua example

SetVariable ("MyName", "Nick Gammon")

Jscript example

world.SetVariable("MyName", "Nick Gammon");

PerlScript example

$world->SetVariable("MyName", "Nick Gammon");

Python example

world.SetVariable("MyName", "Nick Gammon")

VBscript example

world.SetVariable "MyName", "Nick Gammon"

See Also ...

Topics

 Arrays

 Plugins

 Scripting

 Variables

Functions

 DeleteVariable (Deletes a variable)

 GetVariable (Gets the contents of a variable)

 GetVariableList (Gets the list of variables)

(Help topic: function=SetVariable)


SetWorldWindowStatus

Script function

world.SetWorldWindowStatus

 Read about scripting

Type

Method

Summary

Sets the scroll bar position, and hides or shows it

Prototype

long SetScroll(long Position, BOOL Visible);

 View list of data type meanings

Description

This lets you do two things:

    * Hide the existing scroll bar if desired

    * Set the "scroll position" in the output window

The first feature (hiding the scroll bar) lets you, well, hide it, so that you can draw your own wherever you want (eg. with a themed miniwindow somewhere near where the text appears).

The second feature lets your code scroll the text around (so you can still use the existing output buffer) in response to the player clicking and dragging on "your" thumb, or arrows.

A position of -1 means "the end of the window" (which is the number of lines multiplied by the height of the font, minus the size of the output window).

A position of -2 means "no change".

You can use GetInfo (296) to find the current scroll-bar position (and thus add or subtract from it, to scroll up or down small amounts (like a line or a page).

You can use GetInfo (120) to find if the scroll-bar is currently hidden or not.

The existing code adds the font height (GetInfo (212)) to the current scroll position to scroll downwards a line, and subtracts it to scroll up a line.

To scroll up or down pages you need to find the size of the output window text rectangle, and add or subtract that.

Return value

eOK - success

 View list of return code meanings

Lua example

SetScroll (0, false)  -- hide scroll bar, go to top of window

SetScroll (-1, false) -- hide scroll bar, go to end of window

SetScroll (-2, false) -- hide scroll bar, do not change position

SetScroll (-2, true)  -- show scroll bar, do not change position

Lua notes

The Visible flag is optional and defaults to true.

See Also ...

Function

 GetInfo (Gets information about the current world)

(Help topic: function=SetWorldWindowStatus)


ShiftTabCompleteItem

Script function

world.ShiftTabCompleteItem

 Read about scripting

Type

Method

Summary

Adds an item to  the list shown for Shift+Tab completion

Prototype

long ShiftTabCompleteItem(BSTR Item);

 View list of data type meanings

Description

Lets you add an item to the menu that pops up when you type a partial word and hit Shift+Tab in the command window.

The default is, if you type a partial script function name and hit Shift+Tab it will complete the function, as an aid to writing scripts, eg.

col<Shift+Tab> suggests ColourNameToRGB, ColourNote and ColourTell.

Now you can add items of your own to the list (for example, Python functions).

To do this, use this function for each additional word.

For example:

ShiftTabCompleteItem ("repeat")

ShiftTabCompleteItem ("until")

ShiftTabCompleteItem ("while")

You should use the correct capitalization that you want in the finished word.

Words must start with a letter, and then be alphanumeric (A-Z, a-z, 0-9) plus period, underscore, hyphen.

You can use three special words for additional control:

ShiftTabCompleteItem ("<clear>")   --> clears the list of user-added items

ShiftTabCompleteItem ("<nofunctions>")  -->  suppresses the completion of script function names (like ColourTell)

ShiftTabCompleteItem ("<functions>")  --> allows the completion of script function names

These items are not saved in the world file, they should be loaded each time.

You might use the "<nofunctions>" action if you were simply planning to play the MUD, and didn't want script functions popping up in the menu.

Return value

eBadParameter: Empty string supplied, string > 30 characters, or string contains invalid characters

eOK: Added OK

 View list of return code meanings

Lua example

ShiftTabCompleteItem ("repeat")

ShiftTabCompleteItem ("until")

ShiftTabCompleteItem ("while")

-- special strings

ShiftTabCompleteItem ("<clear>")   --> clears the list of user-added items

ShiftTabCompleteItem ("<nofunctions>")  -->  suppresses the completion of script function names (like ColourTell)

ShiftTabCompleteItem ("<functions>")  --> allows the completion of script function names

VBscript example

ShiftTabCompleteItem "Function"

ShiftTabCompleteItem "While"

ShiftTabCompleteItem "vbTrue"

ShiftTabCompleteItem "vbFalse"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=ShiftTabCompleteItem)


ShowInfoBar

Script function

world.ShowInfoBar

 Read about scripting

Type

Method

Summary

Shows or hides the "info" tool bar

Prototype

void ShowInfoBar(BOOL Visible);

 View list of data type meanings

Description

Use this to show or hide the "info" toolbar (the one above the status line).

Return value

Nothing.

Lua example

ShowInfoBar (true) -- show bar

ShowInfoBar (false) -- hide bar

Lua notes

The Visible flag is optional, and defaults to true.

Jscript example

world.ShowInfoBar (true); // show bar

world.ShowInfoBar (false); // hide bar

PerlScript example

$world->ShowInfoBar (1); # show bar

$world->ShowInfoBar (0); # hide bar

Python example

world.ShowInfoBar (True) # show bar

world.ShowInfoBar (False) # hide bar

VBscript example

world.ShowInfoBar vbTrue  ' show bar

world.ShowInfoBar vbFalse  ' hide bar

See Also ...

Topic

 Info bar - programmable information bar

Functions

 Info (Adds text to the "info" tool bar)

 InfoBackground (Sets the background colour for the info bar)

 InfoClear (Clears all text from the info bar)

 InfoColour (Sets the colour of the foreground (text color) for the info bar)

 InfoFont (Changes the font, font size and style for text on the info bar)

 SetStatus (Sets the status line text)

(Help topic: function=ShowInfoBar)


Simulate

Script function

world.Simulate

 Read about scripting

Type

Method

Summary

Simulate input from the MUD, for debugging purposes

Prototype

void Simulate(BSTR Text);

 View list of data type meanings

Description

The argument to this function is supplied to MUSHclient as if it had been sent from the MUD. This is intended for debugging triggers etc, similar to the Game -> Test Trigger menu option.

This should be used with caution inside scripts. If you simulate input inside a trigger, the input causing another trigger to fire, you are likely to get a stack overflow.

An example of using it would be to bind it to a keystroke (like F11), so that if you are testing a trigger that matches on:

Exits: north

... then you might do this:

Accelerator ("F11", "/Simulate 'Exits: north\n' ")

Return value

Nothing.

Lua example

Simulate ("Exits: north\n")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

Simulate ("Exits: north\n");

VBscript example

Simulate "Exits: north" + vbCrLf

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 Debug (Displays debugging information about the world)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=Simulate)


Sound

Script function

world.Sound

 Read about scripting

Type

Method

Summary

Plays a sound

Prototype

long Sound(BSTR SoundFileName);

 View list of data type meanings

Description

This plays the specified sound file, allowing you to add sound-effects to your world.

Also see PlaySound which lets you play multiple sound files at once.

The sound file should have the properties:

* "Wave" file (ie. ending in .wav)

* Audio sample size: 16 bit

* Channels: 2

* Audio sample rate: 22 kHz

* Audio format: PCM

You can use programs like Audacity (which is free) to convert sound files from one format to another.

http://audacity.sourceforge.net/

Return value

eNoNameSpecified: no sound file name given

eCannotPlaySound: cannot play that file

eOK: completed OK

 View list of return code meanings

Lua example

Sound ("ding.wav")

Jscript example

Sound("ding.wav");

PerlScript example

$world->Sound("ding.wav");

Python example

world.Sound("ding.wav")

VBscript example

Sound "ding.wav"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=Sound)


SpeedWalkDelay

Script function

world.SpeedWalkDelay

 Read about scripting

Type

Property

Summary

The number of milliseconds delay between speed walk commands

Prototype

short SpeedWalkDelay;

 View list of data type meanings

Description

This property is used to retrieve, or set, the number of milliseconds which elapses between sending speed walk commands (or commands sent with the Queue method).

The interval is in milliseconds. There are 1000 milliseconds to the second.

The valid range for the speed walk delay is 0 to 30000 milliseconds (0 to 30 seconds).

If the interval is zero, then commands are not queued, but are sent immediately, as fast as possible.

Setting the interval to zero, when it was previously some other value, flushes any outstanding commands from the queue, so they are sent immediately.

Return value

This is a property. You can review or change the number of milliseconds between sending speedwalk commands.

Lua example

Note (GetSpeedWalkDelay ()) -- display delay

SetSpeedWalkDelay (5000) -- make delay 5 seconds

Lua notes

Lua implements this as two functions:

GetSpeedWalkDelay - gets the speedwalk delay

SetSpeedWalkDelay - sets the speedwalk delay

Jscript example

world.note(world.SpeedWalkDelay); // display delay

world.SpeedWalkDelay = 5000; // make delay 5 seconds

PerlScript example

$world->note ($world->{SpeedWalkDelay});  # display delay

$world->{SpeedWalkDelay} = 5000;  # make delay 5 seconds

Python example

world.note(world.SpeedWalkDelay) # display delay

world.SpeedWalkDelay = 5000 # make delay 5 seconds

VBscript example

world.note world.SpeedWalkDelay ' display delay

world.SpeedWalkDelay = 5000 ' make delay 5 seconds

See Also ...

Topics

 Aliases

 Auto-mapper

 Getting started

 Speed walking

Functions

 DiscardQueue (Discards the speed walk queue)

 EvaluateSpeedwalk (Evaluates a speed walk string)

 Queue (Queues a command for sending at the "speed walk" rate.)

 RemoveBacktracks (Removes backtracks from a speed walk string)

 ReverseSpeedwalk (Reverses a speed walk string)

 SpeedWalkDelay (The number of milliseconds delay between speed walk commands)

(Help topic: function=SpeedWalkDelay)


SpellCheck

Script function

world.SpellCheck

 Read about scripting

Type

Method

Summary

Spell checks an arbitrary string of text

Prototype

VARIANT SpellCheck(BSTR Text);

 View list of data type meanings

Description

This function lets you call the MUSHclient spell-checker from a script on any arbitrary text string.

Note that if the spell-check engine has not been initialised (eg. the DLL is not present, or the spell check dictionary is not there), it returns the Empty variant (or nil in Lua).

You supply a string of text to be checked.

If there are no spelling errors, the number zero is returned.

If there are spelling errors, a variant array of all of the misspelt words is returned. You can then iterate through that array to display the misspelt words.

If your spell checker has been configured to detect duplicates (eg. "a bird in the the hand") then they will be returned as duplicated words in the list (eg. "the the"). You could detect that by looking for a space in the returned word.

The spell checking is done with the currently-configured spell-check options (eg. whether words in capitals are checked, whether duplicates are checked).

There is no GUI interface (that is, no "correct this word") dialog box will appear.

Return value

If the spell checker is not available an Empty variant (or nil in Lua).

If there were no spelling errors, a numeric result of zero.

If there were spelling errors, a variant array consisting of each misspelt word. If the same word was misspelt twice, it is only returned once. The array of misspelt words is in alphabetic order.

Lua example

result = SpellCheck (

  "Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

print (type (result))

if result == nil then

  Note "Spell check not available"

elseif result == 0 then

  Note "No spelling errors"

else

 for _, v in pairs (result) do print (v) end

end

VBscript example

result = SpellCheck _

  ("Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

Note vartype (result) ' array of variants will be 8204

if vartype (result) = (vbArray + vbVariant) then

  For Each w In result

      world.note w

    Next

elseif IsEmpty (result) then

  Note "Spell check not available"

else

  Note "No spelling errors"

end if

See Also ...

Topic

 Spell checker

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheckCommand (Spell checks the text in the command window)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: function=SpellCheck)


SpellCheckCommand

Script function

world.SpellCheckCommand

 Read about scripting

Type

Method

Summary

Spell checks the text in the command window

Prototype

long SpellCheckCommand(long StartCol, long EndCol);

 View list of data type meanings

Description

This function lets you call the MUSHclient spell-checker from a script to check the command window.

The intention here is to let you filter out commands that would naturally fail the spell check, and only check ones you want. eg. "say xxx"

You can specify a start and end column (these are 1-relative, that is the first column is column 1). You can use these to remove special words that might be at the start of the command.

eg.

SetRoomDesc "this is my description"

In this case you might make an plugin that matches on:

SetRoomDesc "*"

Inside the plugin you could work out the start and end column for the "real" text and specify that for the spell checker.

If the start column or the end column is less than 1, or the end column is not greater than the start column, then the entire command window will be checked.

eg. to check the entire command window:  SpellCheckCommand (0, 0)

The function returns:

-1 : spell check engine not initialised successfully

0 : spell check cancelled

1 : spell check completed OK

The spell checking is done with the currently-configured spell-check options (eg. whether words in capitals are checked, whether duplicates are checked).

If there is a spelling error in the selected text, a GUI window will pop-up requesting corrective action.

The the Lua example below for a suggested way of conditionally spellchecking certain commands. Make a plugin, and in that plugin put the function OnPluginCommand. This is called every time you send a command to the MUD.

In the script below it does a regular expression check to find what command you have entered. In the example if you "say" or "tell" something, then the "something" part (the captured pattern) is sent to SpellCheckCommand with the start and end column being those from the regular expression capture.

If the check fails, it returns false to stop sending the command.

If the check succeeds, it gets the command text from the command window, in case the spell check changed it.

If it changed, it returns false to stop *this* command being sent, and does a "Send" of the modified one.

If it didn't change (ie. no spelling errors at all, or the errors were ignored) then the original command is allowed to proceed.

Return value

-1 : spell check engine not initialised successfully

0 : spell check cancelled (cancel button pressed)

1 : spell check completed OK (possibly after amending the text in the window)

Lua example

function OnPluginCommand (sText)

  a, b, c = rex.new ("(?:say|tell) (.+)"):exec (sText)

  if a == nil then

    return true  -- not matched our regular expression

  end	-- if

  -- matched regular expression - check the command

  check = SpellCheckCommand (c [1], c [2])

  -- if check failed, cancel sending

  if check == 0 then

    return false	-- cancelled, don't process

  end

  -- if command hasn't changed, allow it to go

  if GetCommand () == sText then

    return true

  end

  -- get the amended command, send that instead

  Send (GetCommand ())

  return false

end

VBscript example

result = SpellCheckCommand (5, 20)

if result = 0 then

  Note "spelling error detected"

end if

See Also ...

Topic

 Spell checker

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckDlg (Spell checks an arbitrary string of text, invloking the spell-checker dialog)

(Help topic: function=SpellCheckCommand)


SpellCheckDlg

Script function

world.SpellCheckDlg

 Read about scripting

Type

Method

Summary

Spell checks an arbitrary string of text, invloking the spell-checker dialog

Prototype

VARIANT SpellCheckDlg(BSTR Text);

 View list of data type meanings

Description

This function lets you call the MUSHclient spell-checker from a script on any arbitrary text string.

Note that if the spell-check engine has not been initialised (eg. the DLL is not present, or the spell check dictionary is not there), it returns the Empty variant (or nil in Lua).

You supply a string of text to be checked.

The corrected string is returned, after the spellchecker dialog box has been invoked, as many times as necessary, for each misspelt word. If the dialog box is canclled them the NULL variant (or nil in Lua) is returned.

Return value

If the spell checker is not available, or if the spellcheck dialog box is cancelled, an Empty variant (or nil in Lua).

Otherwise, the supplied string is returned, with any misspelt words corrected.

Lua example

result = SpellCheckDlg  (

  "Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

print (type (result))

if result == nil then

  Note "Spell check cancelled"

else

  Note ("Corrected string: ", result)

end -- if

VBscript example

result = SpellCheckDlg _

  ("Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

if IsEmpty (result) then

  Note "Spell check cancelled"

else

  Note "Corrected string: " & result

end if

See Also ...

Topic

 Spell checker

Functions

 AddSpellCheckWord (Adds a word to the user spell check dictionary)

 SpellCheck (Spell checks an arbitrary string of text)

 SpellCheckCommand (Spell checks the text in the command window)

(Help topic: function=SpellCheckDlg)


StopEvaluatingTriggers

Script function

world.StopEvaluatingTriggers

 Read about scripting

Type

Method

Summary

Stops trigger evaluation

Prototype

void StopEvaluatingTriggers(BOOL AllPlugins);

 View list of data type meanings

Description

Call this function from a trigger script to stop trigger evaluation. This would have to be called from "send to script" (not send-to-script-after-omit), nor from a trigger script file, in order to be effective.

This causes trigger evaluation to stop, for the current line, and the current plugin. If not in a plugin, then all triggers in the "main" world trigger list stop being evaluated.

If the argument is true, then no further trigger evaluation takes place, in any further plugins.

Note that since calling a trigger script (script name in Script box) is done after all triggers are evaluated for that plugin, doing this inside a script file will be too late (for the current plugin). It has to be done in send-to-script.

Return value

None.

Lua example

StopEvaluatingTriggers (true)

See Also ...

Topics

 Aliases

 Default triggers/aliases/timers/macros/colours

 Getting started

 Groups

 Plugins

 Regular Expressions

 Timers

 Triggers

Functions

 AddTrigger (Adds a trigger)

 AddTriggerEx (Adds a trigger - extended arguments)

 DeleteTemporaryTriggers (Deletes all temporary triggers)

 DeleteTrigger (Deletes a trigger)

 DeleteTriggerGroup (Deletes a group of triggers)

 EnableTrigger (Enables or disables a trigger)

 EnableTriggerGroup (Enables/disables a group of triggers)

 GetPluginTriggerInfo (Gets details about a named trigger for a specified plugin)

 GetPluginTriggerList (Gets the list of triggers in a specified plugin)

 GetTrigger (Gets details about a named trigger)

 GetTriggerInfo (Gets details about a named trigger)

 GetTriggerList (Gets the list of triggers)

 GetTriggerOption (Gets the value of a named trigger option)

 GetTriggerWildcard (Returns the contents of the specified wildcard for the named trigger)

 IsTrigger (Tests to see if a trigger exists)

 SetTriggerOption (Sets the value of a named trigger option)

(Help topic: function=StopEvaluatingTriggers)


StopSound

Script function

world.StopSound

 Read about scripting

Type

Method

Summary

Stop playing a sound started by PlaySound

Prototype

long StopSound(short Buffer);

 View list of data type meanings

Description

Stops one, or all, sound buffers from playing.

It is not necessary to call this for non-looping sounds, which stop of their own accord anyway, however doing so would free up the memory used by the sound.

The buffer argument specifies which buffer to stop (1 to 10) or 0 to stop all sound buffers playing.

Return value

eBadParameter: Buffer number outside range 0 to 10

eOK: Requested buffer(s) have been stopped.

 View list of return code meanings

Lua example

StopSound (0)  -- Stop playing all sounds

StopSound (1)  -- Stop playing sound buffer #1

Lua notes

The buffer number is optional and defaults to zero, which will stop all sounds from playing.

VBscript example

StopSound 0  ' Stop playing all sounds

StopSound 1 ' Stop playing sound buffer #1

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=StopSound)


StripANSI

Script function

world.StripANSI

 Read about scripting

Type

Method

Summary

Strips ANSI colour sequences from a string

Prototype

BSTR StripANSI(BSTR Message);

 View list of data type meanings

Description

This removes ANSI colour sequences from a string.

The intention of this routine is to be used with incoming chat messages (which may have ANSI colour codes in them), if you want to display them in a plain colour, or reformat using your own colours.

Return value

The supplied string with ANSI colour sequences removed.

Lua example

Note (StripANSI (incoming_message))

Jscript example

Note (StripANSI (incoming_message));

PerlScript example

Note (StripANSI (incoming_message));

Python example

world.Note (StripANSI (world.incoming_message))

VBscript example

Note StripANSI (incoming_message)

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 ANSI (Generates an ANSI colour sequence)

 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)

 ChatMessage (Sends a message to a chat user (raw format))

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 Note (Sends a note to the output window)

 PlaySound (Plays a sound using DirectSound)

 ReadNamesFile (Loads in a file for generating character names)

 Replace (Replaces one substring with another)

 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)

 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)

 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=StripANSI)


Tell

Script function

world.Tell

 Read about scripting

Type

Method

Summary

Sends a message to the output window - not terminated by a newline

Prototype

void Tell(BSTR Message);

 View list of data type meanings

Description

This makes a note in the output window. It is not transmitted to the world. It is useful for making comments to yourself. The note is NOT automatically terminated by a newline, so you can use Tell multiple times on one line (eg. to change colour in mid-line).

The note appears in the current NoteColour (a custom colour), or in the RGB colours selected by NoteColourFore and NoteColourBack.

You can also choose colours with NoteColourRGB and NoteColourName.

A new line will automatically be started by output from the MUD, or a command that you type being echoed to the output window. You can send a new line yourself by sending vbCRLF (in Visual Basic) or \n in Jscript or Perlscript.

To make changes to the text style (eg. bold, underline) see NoteStyle.

Return value

Nothing.

Lua example

Tell ("This monster is worth avoiding!")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.tell("This monster is worth avoiding!");

PerlScript example

$world->tell("This monster is worth avoiding!");

Python example

world.tell("This monster is worth avoiding!")

VBscript example

world.tell "This monster is worth avoiding!"

See Also ...

Topic

 Notes

Functions

 AnsiNote (Make a note in the output window from text with ANSI colour codes imbedded)

 ColourNote (Sends a message to the output window in specified colours)

 ColourTell (Sends a message to the output window in specified colours - not terminated by a newline)

 DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)

 GetNoteStyle (Gets the style for notes)

 Hyperlink (Creates a hyperlink in the output window)

 Note (Sends a note to the output window)

 NoteColour (Chooses which custom colour will be used for world notes.)

 NoteColourBack (Chooses which RGB colour will be used for world notes - background colour)

 NoteColourFore (Chooses which RGB colour will be used for world notes - text colour)

 NoteColourName (Chooses which RGB colour name will be used for world notes - text and background)

 NoteColourRGB (Chooses which RGB colour will be used for world notes - text and background)

 NoteHr (Draws a horizontal rule in the output window)

 NoteStyle (Sets the style for notes)

 Send (Sends a message to the MUD)

 SetNotes (Sets the notes for the world.)

(Help topic: function=Tell)


TextRectangle

Script function

world.TextRectangle

 Read about scripting

Type

Method

Summary

Specifies the size of the rectangle in which text is displayed in the output window.

Prototype

long TextRectangle(long Left, long Top, long Right, long Bottom, long BorderOffset, long BorderColour, long BorderWidth, long OutsideFillColour, long OutsideFillStyle);

 View list of data type meanings

Description

This reduces the rectangle in which normal MUD output is displayed, from the entire output window, to the subset specified.

This can be used to make a "desktop effect" where you have room on all sides for miniwindows to be placed.

A border can be drawn at the edge of the rectangle to make it obvious where the text ends, to help in resizing the window.

The text is clipped to be within the text rectangle. A window redraw is forced.

Left, Top, Right, Bottom - describes the rectangle in which the text is drawn. If 0,0,0,0 is specified, text is drawn "normally" to the borders of the output window.

BorderOffset - the offset in pixels between the edge of the text, and the border. You can specify a few pixels here so that the text is not jammed up against the border.

BorderColour - the colour to draw the border in (RGB value).

BorderWidth - the width of the border - make zero for no border.

OutsideFillColour - the brush colour to fill the area outside the text rectangle.

OutsideFillStyle - the brush mode to use for the outside fill. See Brush parameters for a description of the various modes. The brush modes can be:

0: solid (filled with a solid colour)

1: null (not filled)

2: hatch: horizontal

3: hatch: vertical

4: hatch: forwards diagonal

5: hatch: backwards diagonal

6: hatch: cross

7: hatch: diagonal cross

8: fine pattern

9: medium pattern

10: coarse pattern

11: waves - horizontal

12: waves - vertical

Return value

eBrushStyleNotValid - invalid brush style specified for OutsideFillStyle

eOK - done OK

 View list of return code meanings

Lua example

TextRectangle(50,   -- left

              100,  -- top

              50 + GetInfo (213) * 80, -- 50 + width for 80 characters

              -100,  -- 100 pixels from the bottom

              5,  -- BorderOffset,

              ColourNameToRGB ("gray"),    -- BorderColour,

              2,  -- BorderWidth,

              ColourNameToRGB ("silver"),  -- OutsideFillColour,

              8) -- OutsideFillStyle (fine hatch)

Lua notes

You can use the following constants for the outside fill style:

miniwin.brush_solid = 0

miniwin.brush_null = 1

miniwin.brush_hatch_horizontal = 2

miniwin.brush_hatch_vertical = 3

miniwin.brush_hatch_forwards_diagonal = 4

miniwin.brush_hatch_backwards_diagonal = 5

miniwin.brush_hatch_cross = 6

miniwin.brush_hatch_cross_diagonal = 7

miniwin.brush_fine_pattern = 8

miniwin.brush_medium_pattern = 9

miniwin.brush_coarse_pattern = 10

miniwin.brush_waves_horizontal = 11

miniwin.brush_waves_vertical = 12

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 Redraw (Schedules a redraw for all windows for this world)

 Repaint (Forces an immediate redraw for all windows for this world)

 SetCursor (Changes the shape of the mouse cursor)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=TextRectangle)


Trace

Script function

world.Trace

 Read about scripting

Type

Property

Summary

Trace mode property

Prototype

boolean Trace;

 View list of data type meanings

Description

Set to 1 to turn trace mode on, 0 to turn it off.

When trace mode is on debug messages appear in the output window. These occur when:

1. A trigger matches

2. A timer fires

3. An alias matches

4. A script executes

5. A script calls TraceOut.

Return value

This is a property. You can use it to find whether trace mode is on.

Lua example

SetTrace (true)   -- turn trace on

SetTrace (false)   -- turn trace off

Note(GetTrace ())  -- display whether trace is on

Lua notes

Lua implements this as two functions:

GetTrace - gets whether tracing occurs

SetTrace - sets whether tracing occurs

The argument is optional, and defaults to true.

Jscript example

world.trace = 1;   // turn trace on

world.trace = 0;   // turn trace off

world.Note(world.Trace);  // display whether trace is on

PerlScript example

$world->{trace} = 1;   # trace mode on

$world->{trace} = 0;   # trace mode off

$world->note($world->{trace});  # display whether trace is on

Python example

world.trace = 1   # turn trace on

world.trace = 0   # turn trace off

world.Note(world.Trace)  # display whether trace is on

VBscript example

world.trace = 1   ' turn trace on

world.trace = 0   ' turn trace off

world.note world.trace  ' display whether trace is on

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=Trace)


TraceOut

Script function

world.TraceOut

 Read about scripting

Type

Method

Summary

Outputs the supplied message to the world Trace

Prototype

void TraceOut(BSTR Message);

 View list of data type meanings

Description

If tracing is enabled for this world, the supplied string will be output to the trace destination. Normally this would be by world.Note, however if you are using a plugin with OnPluginTrace inside it, then it will be sent to there instead.

eg.

TraceOut ("debug point 3")

Return value

Nothing.

Lua example

TraceOut ("debug point 3")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

TraceOut ("debug point 3")

VBscript example

TraceOut "debug point 3"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=TraceOut)


TranslateDebug

Script function

world.TranslateDebug

 Read about scripting

Type

Method

Summary

Sends a debugging message to the localizing translator script

Prototype

long TranslateDebug(BSTR Message);

 View list of data type meanings

Description

This sends a message to the translator script loaded at MUSHclient startup (if any). For example, if you had en.lua in the "locale" directory, it would be sent to the script space for that file (if EN was your locale).

The intention here is for that script to do things like monitor its performance (eg. count the number of times a string is translated) and display such counts when requested.

The message is passed to a function named "Debug" in the translator script (if found).

The function might look like this:

function Debug (message)

  if message == "display" then

    -- display counts

  elseif message == "reset" then

    -- reset counts

  end -- if

end -- function Debug

Return value

0 = called script OK

1 = script file not loaded (eg. no xx.lua file)

2 = function named Debug was not found in the script

3 = runtime error calling the function Debug

Lua example

TranslateDebug ("general")

Lua notes

The Message argument is optional, and defaults an empty string.

Jscript example

world.TranslateDebug ("display");

PerlScript example

$world->TranslateDebug ("display");

Python example

world.TranslateDebug ("display")

VBscript example

world.TranslateDebug "display"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 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=TranslateDebug)


TranslateGerman

Script function

world.TranslateGerman

 Read about scripting

Type

Method

Summary

Translate German umluat sequences

Prototype

BSTR TranslateGerman(BSTR Text);

 View list of data type meanings

Description

This function translates various German sequences to the non-umluat versions for MUDs that do not support umluats, as follows:

 ü to ue

 Ü to Ue

 ä to ae

 Ä to Ae

 ö to oe

 Ö to Oe

 ß to ss

Return value

The supplied text with the sequences described above replaced.

Lua example

Send (TranslateGerman ("ü"))

Jscript example

Send (TranslateGerman ("ü"));

VBscript example

Send TranslateGerman ("ü")

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 Transparency (Sets the transparency of the main MUSHclient window under Windows XP)

 Trim (Trims leading and trailing spaces from a string)

(Help topic: function=TranslateGerman)


Transparency

Script function

world.Transparency

 Read about scripting

Type

Method

Summary

Sets the transparency of the main MUSHclient window under Windows XP

Prototype

boolean Transparency(long Key, short Amount);

 View list of data type meanings

Description

Under Windows XP or later operating systems, you can make the MUSHclient window semi-transparent, so that the underlying windows "show through". Under Windows NT/2000/95/98/ME this function does nothing.

Key: specifies the transparency colour key to be used when composing the layered window. All pixels painted by the window in this color will be transparent. This is an RGB code, you can use ColourNameToRGB to convert a name to RGB.

If the key is -1 then there is no colour key.

Amount: the amount of transparency for other colours, in the range 0 to 255. If outside this range the number will be coerced into it.

WARNING

Drawing transparent windows may slow down the program, as the operating system has to render to an off-screen bitmap and copy to the main window. This slow-down may not be obvious on fast PCs.

Return value

On success, returns true.

On failure, returns false (eg. under Windows 95).

Lua example

Transparency (-1, 127) -- Make everything 50% transparent

Transparency (0, 255)  -- Black is transparent, everything else is full intensity

Transparency (ColourNameToRGB ("red"), 64)  -- Red is transparent, everything else is 25% transparent

VBscript example

Transparency -1, 127  ' Make everything 50% transparent

Transparency 0, 255   ' Black is transparent, everything else is full intensity

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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)

 ColourNameToRGB (Converts a named colour to a RGB colour code.)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

 Trim (Trims leading and trailing spaces from a string)

(Help topic: function=Transparency)


Trim

Script function

world.Trim

 Read about scripting

Type

Method

Summary

Trims leading and trailing spaces from a string

Prototype

BSTR Trim(BSTR Source);

 View list of data type meanings

Description

This is supplied as a convenient way of removing leading and trailing spaces from a supplied string.

Return value

The source string with any leading or trailing spaces removed.

Lua example

Note("*" .. Trim("  mystring  ") .. "*")

Jscript example

world.Note("*" + world.Trim("  mystring  ") + "*");

PerlScript example

$world->Note("*" . $world->Trim("  mystring  ") . "*");

Python example

world.Note("*" + world.Trim("  mystring  ") + "*")

VBscript example

world.note "*" & world.trim ("  mystring  ") & "*"

See Also ...

Topics

 Scripting

 Utilities

Functions

 AddFont (Adds a custom font for use by MUSHclient)

 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 &#x5C;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)

 ImportXML (Imports configuration data in XML format)

 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)

 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)

 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)

(Help topic: function=Trim)


UdpListen

Script function

world.UdpListen

 Read about scripting

Type

Method

Summary

Listens for incoming packets using the UDP protocol

Prototype

long UdpListen(BSTR IP, short Port, BSTR Script);

 View list of data type meanings

Description

This lets you set up a plugin script function that will be called whenever a UDP packet arrives on the specified port.

This lets you set up a separate program which can communicate with MUSHclient by sending it UDP packets.

The maximum size message that can be received is 999 bytes. In practice, attempting to receive more than 512 bytes may fail due to fragmentation over the network. Note that UDP packets are not guaranteed to arrive, or may arrive out of order. If UDP packets are fragmented by routers, and any fragment does not arrive, then the whole packet is discarded.

UDP is best used in situations where smallish amounts of data, which are not critical that they arrive at all, or in sequence, need to be sent. An example would be something like player or mob status information, where if one packet is lost, another would arrive shortly afterwards, and the loss of a single packet would be an inconvenience, not a disaster.

To listen to messages from any address use the address "0.0.0.0".

The address must be a dotted number, not a name (eg. "10.0.0.8")

You can cancel a listener by calling this function (for a previously-setup port) with an empty script name.

The script must be in a plugin, and be defined to accept a single string (which is the text that arrives in the UDP packet). For example, in Lua:

function listener (s)

  --  process UDP packet "s" here

end -- listener

Return value

eNotAPlugin: This must be called from a plugin

eBadParameter: The port is already in use by another plugin, or the UDP socket could not be created

eNoNameSpecified: No script name was specified

eOK: succeeded

 View list of return code meanings

Lua example

-- listening function in plugin:

function listener (s)

  ColourNote ("white", "blue", "Got UDP packet: " .. s)

end -- listener

-- set up listener

require "check"

check (UdpListen ("0.0.0.0", 4111, "listener"))

Jscript example

UdpListen ("0.0.0.0", 4111, "MyScript")

VBscript example

UdpListen "0.0.0.0", 4111, "MyScript"

See Also ...

Functions

 GetUdpPort (Find a free port for UDP listening)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 UdpSend (Sends a packet over the network using the UDP protocol)

(Help topic: function=UdpListen)


UdpPortList

Script function

world.UdpPortList

 Read about scripting

Type

Method

Summary

Returns an array of all the UDP ports in use by this world

Prototype

VARIANT UdpPortList();

 View list of data type meanings

Description

Returns a variant array of all the UDP ports that are being listened to by plugins for this world. eg.

4223

4224

Return value

If there are no ports in use then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the port numbers in use.

Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of ports in the list).

Lua example

-- show all ports

for _, v in pairs (UdpPortList()) do

  Note (v)

end

VBscript example

dim portList

portList= world.UdpPortList

If Not IsEmpty (portList) Then

  For Each v In portList

    world.note v

  Next

End If

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetUdpPort (Find a free port for UDP listening)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpListen (Listens for incoming packets using the UDP protocol)

 UdpSend (Sends a packet over the network using the UDP protocol)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=UdpPortList)


UdpSend

Script function

world.UdpSend

 Read about scripting

Type

Method

Summary

Sends a packet over the network using the UDP protocol

Prototype

long UdpSend(BSTR IP, short Port, BSTR Text);

 View list of data type meanings

Description

This sends a single UDP (User Datagram Protocol) packet over the network, to the specified IP address and port.

The intention here is to communicate with other programs, such as the status-bar stand-alone program using UDP to send short messages.

You can broadcast to more than one PC by using a broadcast address.

The address must be a dotted number, not a name (eg. 10.0.0.8)

Return value

If the packet was sent successfully, zero is returned.

If the address could not be decoded, -1 is returned;

For other socket errors the Windows socket error number.

Lua example

UdpSend ("10.0.0.3", 4111, "magic,textcolour,5555")

Jscript example

UdpSend ("10.0.0.3", 4111, "magic,textcolour,5555")

VBscript example

UdpSend "10.0.0.3", 4111, "magic,textcolour,5555"

See Also ...

Functions

 GetUdpPort (Find a free port for UDP listening)

 UdpListen (Listens for incoming packets using the UDP protocol)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

(Help topic: function=UdpSend)


UnloadPlugin

Script function

world.UnloadPlugin

 Read about scripting

Type

Method

Summary

Unloads an installed plugin

Prototype

long UnloadPlugin(BSTR PluginID);

 View list of data type meanings

Description

Unloads (removes from MUSHclient world space) the specified plugin.

You can specify the plugin by unique ID, or by plugin name (assuming the name is unique in your list of plugins).

eg.

world.ReloadPlugin "chat"

world.ReloadPlugin "753ba7e011f3c8943a885f18"

However, a plugin cannot unload itself. That would mean the script was deleted out from under itself. If you try to work around that by having plugin A call plugin B, and plugin B unloads plugin A, you will probably get a crash. If you really want to make a "unload myself" function in a plugin, use something like DoAfterSpecial, to send the "UnloadPlugin" command to the script engine after a 1-second delay.

The check for plugin name or plugin ID is not case-sensitive.

Return value

eNoSuchPlugin: Plugin is not currently installed

eBadParameter: Cannot unload ourselves

eOK: Unloaded OK

 View list of return code meanings

Lua example

UnloadPlugin ("chat")

UnloadPlugin ("753ba7e011f3c8943a885f18")

Jscript example

world.UnloadPlugin ("chat");

world.UnloadPlugin ("753ba7e011f3c8943a885f18");

PerlScript example

$world->UnloadPlugin ("chat");

$world->UnloadPlugin ("753ba7e011f3c8943a885f18");

Python example

world.UnloadPlugin ("chat")

world.UnloadPlugin ("753ba7e011f3c8943a885f18")

VBscript example

UnloadPlugin "chat"

UnloadPlugin "753ba7e011f3c8943a885f18"

See Also ...

Topics

 Aliases

 Arrays

 Plugins

 Scripting

 Timers

 Triggers

 Variables

Functions

 BroadcastPlugin (Broadcasts a message to all installed plugins)

 CallPlugin (Calls a routine in a plugin)

 EnablePlugin (Enables or disables the specified plugin)

 GetPluginID (Returns the 24-character ID of the current plugin)

 GetPluginInfo (Gets details about a specified plugin)

 GetPluginList (Gets a list of installed plugins.)

 GetPluginName (Returns the name of the current plugin)

 GetPluginTimerInfo (Gets details about a named timer for a specified plugin)

 GetPluginTimerList (Gets the list of timers in a specified plugin)

 GetPluginVariable (Gets the contents of a variable belonging to a plugin)

 GetPluginVariableList (Gets the list of variables in a specified plugin)

 IsPluginInstalled (Checks to see if a particular plugin is installed)

 LoadPlugin (Loads a plugin from disk)

 PluginSupports (Checks if a plugin supports a particular routine)

 ReloadPlugin (Reloads an installed plugin)

 SaveState (Saves the state of the current plugin)

(Help topic: function=UnloadPlugin)


Version

Script function

world.Version

 Read about scripting

Type

Method

Summary

Gets the MUSHclient version string.

Prototype

BSTR Version();

 View list of data type meanings

Description

This returns the MUSHclient version string. This is usually a "number" like "3.10" but might have letters appended if it is a beta or test version (eg. "3.10.2" or "3.10p22").

Return value

MUSHclient version string.

Lua example

Note(Version())

Jscript example

world.Note(world.Version());

PerlScript example

$world->Note($world->Version());

Python example

world.Note(world.Version)

VBscript example

world.note world.Version

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=Version)


WindowAddHotspot

Script function

world.WindowAddHotspot

 Read about scripting

Type

Method

Summary

Adds a hotspot  to a miniwindow

Prototype

long WindowAddHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom, BSTR MouseOver, BSTR CancelMouseOver, BSTR MouseDown, BSTR CancelMouseDown, BSTR MouseUp, BSTR TooltipText, long Cursor, long Flags);

 View list of data type meanings

Description

Each miniwindow can have any number of hotspots (including zero). Each one designates a rectangle which has some significance if you mouse over it, or click inside it. You should take care not to overlap hotspot rectangles or they may not behave as you expect. When checking for mouse clicks, hotspots are evaluated in ascending alphabetic order by hotspot id.

Hotspots are not, in themselves, visible graphic elements. You would normally associate them with a piece of text (for a hyperlink) or a graphical element such as a button or checkbox. For example, when drawing text, you know the starting point of the text, the height of the text, and the width of the text. This can be used to create a hotspot over the same place the text appeared.

Most of the functionality of hotspots is provided by script "callbacks" - that is, when you mouse over a hotspot, a function in your main script file, or plugin, is called (if you nominate one).

NOTE: Hotspot functions must be visible to MUSHclient when querying the script engine. Thus functions declared as "local" in Lua (or something similar in other languages) will not work.

WARNING: If you set the "draw underneath" flag when calling WindowCreate, then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

WARNING: If you set the "ignore mouse" flag when calling WindowCreate, then you cannot use hotspots, as mouse clicks and movement will not be detected.

If you want to handle dragging (moving the mouse after clicking), see also WindowDragHandler.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id".

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id to be associated with this particular hotspot. Hotspot IDs are case-sensitive.

Left, Top, Right, Bottom - describes the hotspot rectangle.

MouseOver - the name of the script function to be called when you mouse over the hotspot rectangle

CancelMouseOver - the name of the script function to be called when you move the mouse away from the hotspot rectangle

MouseDown - the name of the script function to be called when you mouse down in the hotspot rectangle

CancelMouseDown - the name of the script function to be called when you release the mouse not in the hotspot rectangle that the mouse-down occurred in

MouseUp - the name of the script function to be called when you release the mouse in the hotspot rectangle that the mouse-down occurred in

TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text.

To change a tooltip later, see: WindowHotspotTooltip

Cursor - a number which indicates what shape the mouse pointer is to take when over the hotspot, as follows:

-1: no cursor

0: arrow

1: hand

2: I-beam

3: + symbol

4: wait (hour-glass)

5: up arrow

6: arrow nw-se

7: arrow ne-sw

8: arrow e-w

9: arrow n-s

10: arrow - all ways

11: (X) cannot do action

12: help (? symbol)

Flags - flags to modify hotspot behaviour. These should be or'd together.

0x01 : All mouse-over events are reported to the mouseover callback (if any)

For subsequent mouse-overs within a single hotspot the flags will have the 0x80 bit set. For the first mouse-over the 0x80 bit will be clear.

The callback functions should look like this:

function mouseover (flags, hotspot_id)

  Note ("we moused over hotspot " .. hotspot_id)

  return 0  -- needed for some languages

end -- mouseover

Since the hotspot ID is passed to the callback function, you can share the same function amongst all your hotspots. For example, a "mouse down" function could handle all the hyperlinks in a miniwindow - by using the hotspot ID, it could look up in a table what action to perform for this particular hotspot.

The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

The flags parameter is a bit mask as follows:

0x01 - Shift key down

0x02 - Control key down

0x04 - Alt key down

0x10 - LH mouse

0x20 - RH mouse

0x40 - double-click

0x80 - mouse-over not first time

0x100 - scroll wheel scrolled (towards you)

0x200 - middle mouse

So, for example, if the left-hand mouse was double-clicked whilst the shift and control keys were held down, the flags would be:

flags = 0x01 + 0x02 + 0x10 + 0x40   --> namely 0x53 (83 in decimal)

You could test this in Lua like this:

if bit.band (flags, 0x20) ~= 0 then

  -- mouse be RH mouse

end -- if

WARNING: The hotspot callbacks are not functions, but names of functions. That is, they should be supplied as string arguments. The supplied names are looked up in the script space at the appropriate time.

WARNING: The hotspot callbacks have to be in the same script space as each other (either all in the same plugin, or the world script file).

Return value

eNoSuchWindow - no such miniwindow

eInvalidObjectLabel - one of the script functions is not a valid function name

eHotspotPluginChanged - the plugin is not the same one as used before for hotspots

eItemInUse - attempt to add a hotspot in the middle of adding a hotspot

eOK - completed OK

 View list of return code meanings

Lua example

WindowAddHotspot(win, "hs1",

                 10, 10, 60, 20,   -- rectangle

                 "mouseover",

                 "cancelmouseover",

                 "mousedown",

                 "cancelmousedown",

                 "mouseup",

                 "Click here to be healed",  -- tooltip text

                 miniwin.cursor_hand,        -- hand cursor

                 0)                          -- flags

Lua notes

The handler function names can be omitted and default to the empty string (ie. no function).

The Cursor and Flags arguments are optional and default to zero.

You can use the following constants for the cursor:

miniwin.cursor_none = -1

miniwin.cursor_arrow = 0

miniwin.cursor_hand = 1

miniwin.cursor_ibeam = 2

miniwin.cursor_plus = 3

miniwin.cursor_wait = 4

miniwin.cursor_up = 5

miniwin.cursor_nw_se_arrow = 6

miniwin.cursor_ne_sw_arrow = 7

miniwin.cursor_ew_arrow = 8

miniwin.cursor_ns_arrow = 9

miniwin.cursor_both_arrow = 10

miniwin.cursor_x = 11

miniwin.cursor_help = 12

You can use the following constants for the flags:

miniwin.hotspot_report_all_mouseovers = 1

In the callback functions (called on mousedown etc.) you can use the following constants for the flags (first argument to the callback):

miniwin.hotspot_got_shift = 1

miniwin.hotspot_got_control = 2

miniwin.hotspot_got_alt = 4

miniwin.hotspot_got_lh_mouse = 16

miniwin.hotspot_got_rh_mouse = 32

miniwin.hotspot_got_dbl_click = 64

miniwin.hotspot_got_not_first = 128

miniwin.hotspot_got_middle_mouse = 512

miniwin.wheel_got_shift = 1

miniwin.wheel_got_control = 2

miniwin.wheel_got_alt = 4

miniwin.wheel_scroll_back = 256

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowAddHotspot)


WindowArc

Script function

world.WindowArc

 Read about scripting

Type

Method

Summary

Draws an arc in a miniwindow

Prototype

long WindowArc(BSTR WindowName, long Left, long Top, long Right, long Bottom, long x1, long y1, long x2, long y2, long PenColour, long PenStyle, long PenWidth);

 View list of data type meanings

Description

This draws an arc from x1,y1 to x2,y2 inside the box (Left,Top,Right,Bottom) with the designated pen.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Left, Top, Right, Bottom - describes the rectangle into which the arc must fit.

x1, y2 - the starting point for the arc - this point does not have to lie exactly on the arc.

x2, y2 - the ending point for the arc - this point does not have to lie exactly on the arc.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eOK - completed OK

 View list of return code meanings

Lua example

WindowArc (win, 20, 20, 80, 80, 30, 30, 120, 50, ColourNameToRGB ("green"), 0, 4)

Lua notes

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowArc)


WindowBezier

Script function

world.WindowBezier

 Read about scripting

Type

Method

Summary

Draws a Bézier curve in a miniwindow

Prototype

long WindowBezier(BSTR WindowName, BSTR Points, long PenColour, long PenStyle, long PenWidth);

 View list of data type meanings

Description

Draws one or more Bézier splines. This function draws cubic Bézier splines by using the endpoints and control points specified by the Points parameter. The first spline is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent spline in the sequence needs exactly three more points: the end point of the previous spline is used as the starting point, the next two points in the sequence are control points, and the third is the end point.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Points - a string consisting of pairs of numbers, one for each point, in the format x1,y1,x2,y2 ...

For example: "20,50,180,50" would specify two points, one at 20,50 and one at 180,50.

You must have at least 4 points (the start, and 3 points per spline), which is 8 numbers. The number of numbers in the string must be even (divisible by two), as it takes a pair of numbers to specify one point. Also, since you need 3 points per spline, the number of numbers in the Points string must have a remainder of 2 when divided by 6 (3 points per spline, plus the start point).

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eInvalidNumberOfPoints - number of numbers supplied does not give a remainder of 2 after dividing by 6, or is less than 8.

eOK - completed OK

 View list of return code meanings

Lua example

WindowBezier (win, "30, 20, 5, 90, 50, 90, 80, 30",

              ColourNameToRGB("blue"), 0, 2)

Lua notes

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowBezier)


WindowBlendImage

Script function

world.WindowBlendImage

 Read about scripting

Type

Method

Summary

Blends an image into a miniwindow, using a specified blending mode

Prototype

long WindowBlendImage(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, short Mode, double Opacity, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

 View list of data type meanings

Description

This blends the specified image into the miniwindow, on top of the specified rectangle.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have previously loaded.

Left, Top, Right, Bottom - describes the destination rectangle. The blend image is merged with the contents of this rectangle to produce the blended result.

Mode - the blending method.

Mode 1 - Normal

Mode 2 - Average

Mode 3 - Interpolate

Mode 4 - Dissolve

Mode 5 - Darken

Mode 6 - Multiply

Mode 7 - Colour Burn

Mode 8 - Linear Burn

Mode 9 - Inverse Colour Burn

Mode 10 - Subtract

Mode 11 - Lighten

Mode 12 - Screen

Mode 13 - Colour Dodge

Mode 14 - Linear Dodge

Mode 15 - Inverse Colour Dodge

Mode 16 - Add

Mode 17 - Overlay

Mode 18 - Soft Light

Mode 19 - Hard Light

Mode 20 - Vivid Light

Mode 21 - Linear Light

Mode 22 - Pin Light

Mode 23 - Hard Mix

Mode 24 - Difference

Mode 25 - Exclusion

Mode 26 - Reflect

Mode 27 - Glow

Mode 28 - Freeze

Mode 29 - Heat

Mode 30 - Negation

Mode 31 - Phoenix

Mode 32 - Stamp

Mode 33 - Xor

Mode 34 - And

Mode 35 - Or

Mode 36 - Red

Mode 37 - Green

Mode 38 - Blue

Mode 39 - Yellow

Mode 40 - Cyan

Mode 41 - Magenta

Mode 42 - Green limited by red

Mode 43 - Green limited by blue

Mode 44 - Green limited by average of red and blue

Mode 45 - Blue limited by red

Mode 46 - Blue limited by green

Mode 47 - Blue limited by average of red and green

Mode 48 - Red limited by green

Mode 49 - Red limited by blue

Mode 50 - Red limited by average of green and blue

Mode 51 - Red only

Mode 52 - Green only

Mode 53 - Blue only

Mode 54 - Discard red

Mode 55 - Discard green

Mode 56 - Discard blue

Mode 57 - All red

Mode 58 - All green

Mode 59 - All blue

Mode 60 - Hue mode

Mode 61 - Saturation mode

Mode 62 - Colour mode

Mode 63 - Luminance mode

Mode 64 - HSL

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the blend image. An opacity of 1 means the blend is fully applied. An opacity of 0.5 means the blended image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

When blending, whichever rectangle is smaller is the one used for the width and height of the operation (the destination rectangle or the source rectangle).

See also BlendPixel for blending individual pixels.

For more information and screen shots showing the effects of various modes, see:

http://www.gammon.com.au/mushclient/mw_blending.htm

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage

eBadParameter - Opacity less than zero or greater than 1.

eOK - completed OK

 View list of return code meanings

Lua example

WindowBlendImage (win, "im", 0, 0, 0, 0, 1, 0.5)  -- mode 1 (normal) at 50% opacity

Lua notes

In Lua you can use the following constants for the blending modes:

miniwin.blend_normal = 1

miniwin.blend_average = 2

miniwin.blend_interpolate = 3

miniwin.blend_dissolve = 4

miniwin.blend_darken = 5

miniwin.blend_multiply = 6

miniwin.blend_colour_burn = 7

miniwin.blend_linear_burn = 8

miniwin.blend_inverse_colour_burn = 9

miniwin.blend_subtract = 10

miniwin.blend_lighten = 11

miniwin.blend_screen = 12

miniwin.blend_colour_dodge = 13

miniwin.blend_linear_dodge = 14

miniwin.blend_inverse_colour_dodge = 15

miniwin.blend_add = 16

miniwin.blend_overlay = 17

miniwin.blend_soft_light = 18

miniwin.blend_hard_light = 19

miniwin.blend_vivid_light = 20

miniwin.blend_linear_light = 21

miniwin.blend_pin_light = 22

miniwin.blend_hard_mix = 23

miniwin.blend_difference = 24

miniwin.blend_exclusion = 25

miniwin.blend_reflect = 26

miniwin.blend_glow = 27

miniwin.blend_freeze = 28

miniwin.blend_heat = 29

miniwin.blend_negation = 30

miniwin.blend_phoenix = 31

miniwin.blend_stamp = 32

miniwin.blend_xor = 33

miniwin.blend_and = 34

miniwin.blend_or = 35

miniwin.blend_red = 36

miniwin.blend_green = 37

miniwin.blend_blue = 38

miniwin.blend_yellow = 39

miniwin.blend_cyan = 40

miniwin.blend_magenta = 41

miniwin.blend_green_limited_by_red = 42

miniwin.blend_green_limited_by_blue = 43

miniwin.blend_green_limited_by_average_of_red_and_blue = 44

miniwin.blend_blue_limited_by_red = 45

miniwin.blend_blue_limited_by_green = 46

miniwin.blend_blue_limited_by_average_of_red_and_green = 47

miniwin.blend_red_limited_by_green = 48

miniwin.blend_red_limited_by_blue = 49

miniwin.blend_red_limited_by_average_of_green_and_blue = 50

miniwin.blend_red_only = 51

miniwin.blend_green_only = 52

miniwin.blend_blue_only = 53

miniwin.blend_discard_red = 54

miniwin.blend_discard_green = 55

miniwin.blend_discard_blue = 56

miniwin.blend_all_red = 57

miniwin.blend_all_green = 58

miniwin.blend_all_blue = 59

miniwin.blend_hue_mode = 60

miniwin.blend_saturation_mode = 61

miniwin.blend_colour_mode = 62

miniwin.blend_luminance_mode = 63

miniwin.blend_hsl = 64

See Also ...

Topic

 MiniWindows

Functions

 BlendPixel (Blends a single pixel with another, using a specified blending mode)

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowBlendImage)


WindowCircleOp

Script function

world.WindowCircleOp

 Read about scripting

Type

Method

Summary

Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow

Prototype

long WindowCircleOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long PenColour, long PenStyle, long PenWidth, long BrushColour, long BrushStyle, long Extra1, long Extra2, long Extra3, long Extra4);

 View list of data type meanings

Description

This draws an ellipse, rectangle, round rectangle, chord or pie, controlled by the Action parameter.

Unlike WindowRectOp described above the rectangles drawn here can be filled with a brush, thus allowing you to have patterned interiors if desired.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of shape to draw, as follows:

1 = Ellipse

2 = Rectangle (however see below)

3 = Round Rectangle

4 = Chord

5 = Pie

Left, Top, Right, Bottom - describes the rectangle into which the shape must fit.

Note for rectangles: Due to the behaviour of the Windows drawing function which this calls, the rectangle excludes the bottom and right-hand edges (that is, stops one pixel short).

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the RGB colour for this brush

BrushStyle - what style of brush to use:

0: solid (filled with a solid colour)

1: null (not filled)

2: hatch: horizontal

3: hatch: vertical

4: hatch: forwards diagonal

5: hatch: backwards diagonal

6: hatch: cross

7: hatch: diagonal cross

8: fine pattern

9: medium pattern

10: coarse pattern

11: waves - horizontal

12: waves - vertical

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

For actions 1 and 2 (ellipse and rectangle):

Extra1, Extra2, Extra3, Extra4 are ignored.

For action 3 (round rectangle):

Extra1 is the width of the ellipse used to draw the rounded corner.

Extra2 is the height of the ellipse used to draw the rounded corner.

Extra3, Extra4 are ignored.

For action 4 (chord):

Extra1, Extra2 is the x, y position of the chord's starting point.

Extra3, Extra4 is the x, y position of the chord's ending point.

For action 5 (pie):

Extra1, Extra2 is the x, y position of the pie's starting point.

Extra3, Extra4 is the x, y position of the pie's ending point.

Return value

eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eBrushStyleNotValid - invalid brush style

eUnknownOption - Action not in list above

eOK - completed OK

 View list of return code meanings

Lua example

-- Ellipses

WindowCircleOp (win, 1, 0, 0, 40, 40,    -- circle

                ColourNameToRGB("blue"), 0, 2, ColourNameToRGB("cyan"), 0)

WindowCircleOp (win, 1, 50, 20, 100, 100, -- ellipse

                ColourNameToRGB("magenta"), 0, 2, ColourNameToRGB("cyan"), 0)

-- Rectangles

WindowCircleOp (win, 2, 5, 5, 40, 40,   -- square

                ColourNameToRGB("blue"), 0, 3, ColourNameToRGB("cyan"), 8)

WindowCircleOp (win, 2, 50, 20, 95, 95, -- rectangle

                ColourNameToRGB("magenta"), 0, 3, ColourNameToRGB("cyan"), 11)

-- Round Rectangle

WindowCircleOp (win, 3, 15, 15, 90, 90,  -- round rectangle

        ColourNameToRGB("blue"), 0, 2, ColourNameToRGB("cyan"), 10, 25, 25)

-- Chord

WindowCircleOp (win, 4, 15, 15, 90, 90,  -- chord

        ColourNameToRGB("green"), 0, 2, ColourNameToRGB("cyan"), 0,

        40, 10, 70, 95)

-- Pie

WindowCircleOp (win, 5, 15, 15, 90, 90,   -- pie

        ColourNameToRGB("green"), 0, 2, ColourNameToRGB("cyan"), 0,

        60, 10, 80, 80)

Lua notes

You can use the following constants for the action:

miniwin.circle_ellipse = 1

miniwin.circle_rectangle = 2

miniwin.circle_round_rectangle = 3

miniwin.circle_chord = 4

miniwin.circle_pie = 5

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

You can use the following constants for the brush style:

miniwin.brush_solid = 0

miniwin.brush_null = 1

miniwin.brush_hatch_horizontal = 2

miniwin.brush_hatch_vertical = 3

miniwin.brush_hatch_forwards_diagonal = 4

miniwin.brush_hatch_backwards_diagonal = 5

miniwin.brush_hatch_cross = 6

miniwin.brush_hatch_cross_diagonal = 7

miniwin.brush_fine_pattern = 8

miniwin.brush_medium_pattern = 9

miniwin.brush_coarse_pattern = 10

miniwin.brush_waves_horizontal = 11

miniwin.brush_waves_vertical = 12

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowCircleOp)


WindowCreate

Script function

world.WindowCreate

 Read about scripting

Type

Method

Summary

Creates a miniwindow

Prototype

long WindowCreate(BSTR WindowName, long Left, long Top, long Width, long Height, short Position, long Flags, long BackgroundColour);

 View list of data type meanings

Description

This creates (or re-creates) a miniwindow of the given name. It is not initially shown so it will be invisible until you call WindowShow. If there is an existing, visible, window of that name, then it will be marked invisible, so you will need to call WindowShow to make it visible again.

If you want to change the size of a miniwindow you don't need to delete it, simply call WindowCreate again, which causes it to be recreated in the new location / size. However you can call WindowDelete to completely delete an existing miniwindow.

Alternatively, call WindowResize which resizes the window, keeping all fonts, images and hotspots.

It is reasonable to use WindowCreate to create a very small window (eg. 0 x 0 pixels) simply to load images or fonts into it. Thus you can find out font sizes, in order to calculate what size window needs to be re-created, so it is the correct size to hold a particular piece of text.

If you call WindowCreate on an existing window then:

* The existing offscreen image will be discarded, and the memory it used freed.

* A new offscreen image will be created, using the new dimensions. Thus you can use WindowCreate to resize a window. For example, you might do this for an inventory window, if you get more inventory.

* The image will be cleared to the background colour you specify.

* Any hotspots you added are removed - unless flag 0x10 is set (create_keep_hotspots), see below. The assumption is that if you are starting drawing from scratch, any hotspot items will probably appear in a different place.

* The window's "show" flag is set to false. Thus you need to call WindowShow before it will become visible.

PARAMETERS:

WindowName - the name we are calling it - needed for all subsequent operations on this miniwindow. We suggest you use GetPluginID () to get a unique name for this window. If you plan to use more than one window in a plugin, simply append "A", "B", etc. to the plugin ID. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Width, Height - the width and height of the window, in pixels. The example window above is 200, 200. The minimum size is 0, 0.

These are required, and lock in the size of the window for subsequent drawing operations. Any attempts to draw outside these boundaries will be clipped.

Position - a number indicating where you want the window positioned on the screen. Whenever the screen is resized or redrawn the contents of the window are drawn in the requested position:

0 = stretch to output view size

1 = stretch with aspect ratio

2 = strech to owner size

3 = stretch with aspect ratio

4 = top left

5 = center left-right at top

6 = top right

7 = on right, center top-bottom

8 = on right, at bottom

9 = center left-right at bottom

10 = on left, at bottom

11 = on left, center top-bottom

12 = centre all

13 = tile

Positions 0 to 3 probably aren't that useful (they are also used for loading background images), and position 13 (tile) would probably not be used often either. However you might use these if you set the "draw underneath" flag described below, so that a subtle window could appear under main output window.

The corner positions (4, 6, 8, 10) always put the miniwindow in that corner, and 12 (centre all) always puts the window dead-centre of the main output window.

The other positions (5, 7, 9, 11) are used for centering the window between the corners. MUSHclient tries to fit the miniwindow exactly in the middle between any corner windows. Also, if more than one window is designated as centered on that side (eg., the right side) it tries to fit them all in, evenly spaced.

If the centered windows can't all be fitted, some are temporarily hidden until they do, in order to avoid overlaps.

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

WARNING: If you set the "draw underneath" flag then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events.

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow.

WARNING: If you set the "ignore mouse" flag then you cannot use hotspots, as mouse clicks and movement will not be detected.

BackgroundColour - this is the RGB code for the colour that the window is initially filled with, and is used when doing transparent drawing, as described above.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Return value

eNoNameSpecified - miniwindow name must be specified

eBadParameter - width or height less than zero

eOK - success

 View list of return code meanings

Lua example

win = "win_" .. GetPluginID ()  -- get a unique name

WindowCreate (win, 0, 0, 200, 200, miniwin.pos_center_all, 0, ColourNameToRGB("white"))  -- create window

WindowShow (win,  true)  -- show it

Lua notes

You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0

miniwin.pos_stretch_to_view_with_aspect = 1

miniwin.pos_stretch_to_owner = 2

miniwin.pos_stretch_to_owner_with_aspect = 3

miniwin.pos_top_left = 4

miniwin.pos_top_center = 5

miniwin.pos_top_right = 6

miniwin.pos_center_right = 7

miniwin.pos_bottom_right = 8

miniwin.pos_bottom_center = 9

miniwin.pos_bottom_left = 10

miniwin.pos_center_left = 11

miniwin.pos_center_all = 12

miniwin.pos_tile = 13

You can use the following constants for the flags:

miniwin.create_underneath = 1

miniwin.create_absolute_location = 2

miniwin.create_transparent = 4

miniwin.create_ignore_mouse = 8

miniwin.create_keep_hotspots = 16

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowCreate)


WindowCreateImage

Script function

world.WindowCreateImage

 Read about scripting

Type

Method

Summary

Creates an image in a miniwindow

Prototype

long WindowCreateImage(BSTR WindowName, BSTR ImageId, long Row8, long Row7, long Row6, long Row5, long Row4, long Row3, long Row2, long Row1);

 View list of data type meanings

Description

This creates a small image (bitmap) by specifying the bit pattern for an 8 x 8 bit image. This is primarily intended for making patterns for use with WindowImageOp, described elsewhere. By designing suitable patterns you could make grass, waves, or other landscape effects for use in maps.

WindowName - the name of an existing miniwindow.

ImageId - the image id to store this image under.

Row1, Row2, Row3, Row4, Row5, Row6, Row7, Row8 - the bit pattern for each row

The easiest way of making your own pattern is to use Lua's tonumber function and work in binary. When doing that, each '1' represents a bit that is set (and is thus in the PenColour) and each '0' represents a bit that is clear (and is thus in the BrushColour).

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

eNoSuchWindow - no such miniwindow

eOK - completed OK

 View list of return code meanings

Lua example

WindowCreateImage (win, "im2",

        tonumber ("11001100", 2),  -- row 8

        tonumber ("11001100", 2),  -- row 7

        tonumber ("00110011", 2),  -- row 6

        tonumber ("00110011", 2),  -- row 5

        tonumber ("11001100", 2),  -- row 4

        tonumber ("11001100", 2),  -- row 3

        tonumber ("00110011", 2),  -- row 2

        tonumber ("00110011", 2))  -- row 1

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowCreateImage)


WindowDelete

Script function

world.WindowDelete

 Read about scripting

Type

Method

Summary

Deletes a miniwindow

Prototype

long WindowDelete(BSTR WindowName);

 View list of data type meanings

Description

This deletes an existing miniwindow, freeing all the resources it used.

WindowName - the name of the existing miniwindow.

This forces a redraw of the output window, so the window is removed from the screen, if necessary.

Return value

eNoSuchWindow - there is no such miniwindow

eOK - success

 View list of return code meanings

Lua example

WindowDelete (win)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDelete)


WindowDeleteAllHotspots

Script function

world.WindowDeleteAllHotspots

 Read about scripting

Type

Method

Summary

Deletes all hotspots from a miniwindow

Prototype

long WindowDeleteAllHotspots(BSTR WindowName);

 View list of data type meanings

Description

This deletes all hotspots from the miniwindow.

WindowName - the name of an existing miniwindow.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

Return value

eNoSuchWindow - no such miniwindow

eOK - completed OK

 View list of return code meanings

Lua example

WindowDeleteAllHotspots (win);

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDeleteAllHotspots)


WindowDeleteHotspot

Script function

world.WindowDeleteHotspot

 Read about scripting

Type

Method

Summary

Deletes a hotspot from a miniwindow

Prototype

long WindowDeleteHotspot(BSTR WindowName, BSTR HotspotId);

 View list of data type meanings

Description

This deletes the hotspot from the miniwindow.

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id to be deleted.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

Return value

eNoSuchWindow - no such miniwindow

eHotspotNotInstalled - no such hotspot

eOK - completed OK

 View list of return code meanings

Lua example

WindowDeleteHotspot (win, "hs1");

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDeleteHotspot)


WindowDragHandler

Script function

world.WindowDragHandler

 Read about scripting

Type

Method

Summary

Adds a drag handler to a miniwindow hotspot

Prototype

long WindowDragHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback, BSTR ReleaseCallback, long Flags);

 View list of data type meanings

Description

Adds drag handler callbacks to the nominated hotspot.

If:

* The user clicks in the hotspot; and

* Moves the mouse; and

* There is a MoveCallback function defined (by using this function)

... then the callback function is called every time the mouse moves (regardless of whether it is still over the current miniwindow).

Also, when the mouse is eventually released, the ReleaseCallback function is called. Unlike the existing mousedown and mouseup functions, these two functions are called no matter where the mouse is - it doesn't even have to be over the MUSHclient window.

This lets you do things like move a window around (eg. drag its title bar), or drag something from one window to another.

There are now WindowInfo selectors (17 and 18) which return the current position of the mouse in "client" coordinates. That is, relative to the output window, not relative to the miniwindow. The mouse position in client coordinates could be used to work out where in the output window the mouse is.

For each miniwindow, WindowInfo selectors 10 to 13 give the current position of that miniwindow (as last drawn), and thus you can work out whether the cursor is over a particular one.

NOTE: Hotspot functions must be visible to MUSHclient when querying the script engine. Thus functions declared as "local" in Lua (or something similar in other languages) will not work.

If you want to change the shape of the cursor as the mouse is being dragged, see SetCursor.

For more information, see:

http://www.gammon.com.au/forum/?id=9254

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id of an existing hotspot.

MoveCallback - the name of the script function to be called when you move the mouse

ReleaseCallback - the name of the script function to be called when you release the mouse

Flags - flags to modify dragging behaviour. Leave as zero, these are not currently used.

To cancel a drag handler, just set the function names to empty strings, eg.

WindowDragHandler(win, "hs1", "", "", 0)

The callback functions should look like this:

function drag_move (flags, hotspot_id)

  -- find where it is now

  local posx = WindowInfo (win, 17)  -- where mouse is relative to output window (X)

  local posy = WindowInfo (win, 18)  -- where mouse is relative to output window (Y)

  -- reposition window here

  return 0  -- needed for some languages

end -- drag_move

The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

The flags parameter is a bit mask as follows:

0x01 - Shift key down

0x02 - Control key down

0x04 - Alt key down

0x10 - LH mouse  (from mouse-down)

0x20 - RH mouse  (from mouse-down)

0x40 - double-click  (from mouse-down)

Note that the mouse was not necessarily clicked on the top-left corner of the miniwindow. Thus a mousedown handler should remember the offset from the edge of the miniwindow when the mouse is clicked (WindowInfo selectors 14 and 15). Then to reposition the window (if that is what you are trying to do) you need to subtract that offset from the values returned by WindowInfo selectors 17 and 18, to get the new location for the top-left corner.

See the example below in the Lua section for more details.

WARNING: The callbacks are not functions, but names of functions. That is, they should be supplied as string arguments. The supplied names are looked up in the script space at the appropriate time.

Return value

eNoSuchWindow - no such miniwindow

eHotspotNotInstalled - no such hotspot

eInvalidObjectLabel - one of the script functions is not a valid function name

eHotspotPluginChanged - the plugin is not the same one as used before for hotspots

eOK - completed OK

 View list of return code meanings

Lua example

-- mouse down function - remember how far in from edge of window mouse was

function mousedown(flags, hotspot_id)

  startx, starty = WindowInfo (win, 14), WindowInfo (win, 15)

end -- mousedown

-- mouse release function - do something useful at the destination location

function dragrelease(flags, hotspot_id)

  print ("mouse drag release for " .. hotspot_id)

  print ("released at position", WindowInfo (win, 17), WindowInfo (win, 18))

end -- dragrelease

function dragmove(flags, hotspot_id)

  print ("moved to position", WindowInfo (win, 17), WindowInfo (win, 18))

  local posx, posy = WindowInfo (win, 17),

                     WindowInfo (win, 18)

  -- move the window to the new location

  WindowPosition(win, posx - startx, posy - starty, 0, 2);

  -- change the mouse cursor shape appropriately

  if posx < 0 or posx > GetInfo (281) or

     posy < 0 or posy > GetInfo (280) then

    check (SetCursor ( 11))   -- X cursor

  else

    check (SetCursor ( 1))   -- hand cursor

  end -- if

end -- dragmove

-- set up the drag handler

WindowDragHandler (win, "hs1", "dragmove", "dragrelease", 0)

Lua notes

The two handler function names can be omitted and default to the empty string (ie. no function).

Flags can be omitted and default to zero.

You can use the following constants for the flags parameter (first parameter) to the callback function called when the mouse is moved or released.

miniwin.drag_got_shift = 1

miniwin.drag_got_control = 2

miniwin.drag_got_alt = 4

miniwin.hotspot_got_lh_mouse = 16

miniwin.hotspot_got_rh_mouse = 32

miniwin.hotspot_got_dbl_click = 64

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDragHandler)


WindowDrawImage

Script function

world.WindowDrawImage

 Read about scripting

Type

Method

Summary

Draws an image into a miniwindow

Prototype

long WindowDrawImage(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, short Mode, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

 View list of data type meanings

Description

This copies an image to the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, Repaint, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded.

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

Mode - the method of drawing the image:

1 - Copy without stretching to the destination position. The image is not clipped, so only the Left and Top parameters are used - the full image is copied to that position.

To copy less than the full image you would need to use the SrcLeft, SrcTop, SrcRight, SrcBottom parameters to specify a smaller part of the image.

2 - Stretch or shrink the image appropriately to fit into the rectangle: Left, Top, Right, Bottom.

3 - Copy without stretching to the position Left, Top. However this is a transparent copy, where the pixel at the left,top corner (pixel position 0,0) is considered the transparent colour. Any pixels that exactly match that colour are not copied. WARNING - do not choose black or white as the transparent colour as that throws out the calculations. Choose some other colour (eg. purple) - you won't see that colour anyway.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

The intention of allowing sub-images was so that you could make up a map by having lots of small images (eg. houses, trees, rocks). Now instead of having to load hundreds of tiny image files into memory, which would doubtless take a while to open all those files, you open a single, larger, file in which the various sub-images are "tiled". For example, you might allocate a 32 x 32 pixel square for each image. Now by selecting the appropriate tile you can copy the sub-image from the main image.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

To draw images which have alpha channels, see WindowDrawImageAlpha.

Note that if you draw a monchrome image, such as one set up by WindowCreateImage then the pen colour from the most recent drawing operation is used as the foreground colour, and the brush colour for the background colour. Thus you may want to draw a small rectangle (eg. 1 x 1 pixel) with WindowCircleOp to establish those colours first.

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage or WindowLoadImageMemory

eBadParameter - drawing mode not in list above

eOK - completed OK

 View list of return code meanings

Lua example

WindowDrawImage (win, "im", 20, 20, 0, 0, 1)  -- straight copy

WindowDrawImage (win, "im", 20, 20, -20, -20, 2)  -- stretch

WindowDrawImage (win, "im", 20, 20, -20, -20, 3)  -- transparent

Lua notes

You can use the following constants for the mode:

miniwin.image_copy = 1

miniwin.image_stretch = 2

miniwin.image_transparent_copy = 3

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDrawImage)


WindowDrawImageAlpha

Script function

world.WindowDrawImageAlpha

 Read about scripting

Type

Method

Summary

Draws an image into a miniwindow respecting the alpha channel

Prototype

long WindowDrawImageAlpha(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, double Opacity, long SrcLeft, long SrcTop);

 View list of data type meanings

Description

This copies an image to the miniwindow, using the alpha channel to show transparent areas.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded (which must have an alpha channel - generally this means it will be 32 bits per pixel, which is 8 bits for each of red, green and blue, and 8 bits for the alpha information).

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the drawn image. An opacity of 1 means the image is fully drawn (apart from where the alpha channel makes part of it opaque). An opacity of 0.5 means the image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop - the source offset in the original image (use 0,0 to get the whole image).

The intention of allowing sub-images was so that you could make up a map by having lots of small images (eg. houses, trees, rocks). Now instead of having to load hundreds of tiny image files into memory, which would doubtless take a while to open all those files, you open a single, larger, file in which the various sub-images are "tiled". For example, you might allocate a 32 x 32 pixel square for each image. Now by selecting the appropriate tile you can copy the sub-image from the main image.

For more information, see:

http://www.gammon.com.au/forum/?id=9568

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage (or WindowLoadImageMemory), or the image does not have an alpha channel.

eBadParameter - opacity not in range 0 to 1.

eOK - completed OK

 View list of return code meanings

Lua example

WindowDrawImageAlpha (win, "im", 20, 20, 0, 0, 1)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowDrawImageAlpha)


WindowFilter

Script function

world.WindowFilter

 Read about scripting

Type

Method

Summary

Performs a filtering operation over part of the miniwindow.

Prototype

long WindowFilter(BSTR WindowName, long Left, long Top, long Right, long Bottom, short Operation, double Options);

 View list of data type meanings

Description

This takes a copy of the specified rectangle in a miniwindow, filters it according to the operation specified, and replaces the filtered version back in place.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Left, Top, Right, Bottom - describes the rectangle to be filtered.

Operation - the filter operation. At present, one of:

1 - Apply colour noise

2 - Apply monochrome noise

3 - Blur (by comparing 2 pixels on each side)

4 - Sharpen

5 - Find edges

6 - Emboss

7 - Adjust Brightness (by adding Options to each pixel)

8 - Adjust Contrast

9 - Adjust Gamma

10 - Adjust Brightness for red channel only  (by adding Options to each pixel)

11 - Adjust Contrast for red channel only

12 - Adjust Gamma for red channel only

13 - Adjust Brightness for green channel only  (by adding Options to each pixel)

14 - Adjust Contrast for green channel only

15 - Adjust Gamma for green channel only

16 - Adjust Brightness for blue channel only  (by adding Options to each pixel)

17 - Adjust Contrast for blue channel only

18 - Adjust Gamma for blue channel only

19 - Convert to grayscale - mix red/green/blue equally

20 - Convert to grayscale - mix 30% red + 59% green + 11% blue for normal perception

21 - Adjust Brightness (by multiplying Options by each pixel)

22 - Adjust Brightness for red channel only  (by multiplying Options by each pixel)

23 - Adjust Brightness for green channel only   (by multiplying Options by each pixel)

24 - Adjust Brightness for blue channel only   (by multiplying Options by each pixel)

25 - Lesser Blur (by comparing 1 pixel on each side)

26 - Minor Blur (by comparing 1 pixel on each side, taking a smaller amount)

27 - Average - the entire rectangle is set to its average colour

Single channel operations - the modes which specify a single channel (10 to 18, 22 to 24) operate on that colour channel only (red, green or blue) leaving the others untouched. Thus by, say, increasing brightness on the red channel you add to the red pixels, but leave green and blue alone, making the image look redder. However decreasing brightness on the red channel would make the image look more cyan (as cyan is the complementary colour to red).

The complementary colours are:

red / cyan

green / magenta

blue / yellow

Options - filtering options.

For the Noise filter:

A number from about 0 to 255 indicating how much noise to add.

For the Blur, Sharpen, Find Edges and Emboss filters:

0 - both directions

1 - horizontal only

2 - vertical only

For the Brightness (additive) filter:

A number from -255 to +255 to indicate the amount to increase (or decrease) the value of each pixel - by adding. A negative number will make it darker, a positive number will make it brighter.

For the Brightness (multiplicative) filter:

A number which is multiplied by the value of each pixel. A number less than 1 will make it darker, a number greater than 1 will make it brighter. However black (zero) will remain black.

For the Contrast filter:

A number to indicate the amount to multiply by the value of each pixel. Zero will make the picture zero contrast, that is totally grey. If you use 1 the pixel will be normal contrast (as each pixel is multiplied by 1). A value between 0 and 1 will be lower contrast. A value above 1 will increase contrast. Negative numbers will have the effect of making the image look negative.

For the Gamma filter:

A number to indicate the amount of Gamma adjustment. Mathematically each pixel is raised to the power of this number. Thus, a gamma of 1 will result in no change. A gamma of 2 will darken the image somewhat. A gamma of 0.5 will lighten the image. A gamma of zero will make the image totally white.

The difference between gamma and brightness is that increasing brightness simply adds to the value of each pixel, so that black becomes gray, and bright pixel become clipped. Similarly, decreasing brightness means that white pixels become grey, and dark ones are clipped.

However because gamma is a power function, black stays black, and white stays white, with the biggest change in the mid range. A higher gamma value results in a darker image with more contrast. A lower gamma value (between 0 and 1) results in a lighter image with less contrast.

Warning - filtering is quite computation-expensive. For example, for a 600 x 600 pixel image, the program has to apply a calculation to 600 x 600 x 3 bytes (one for each of red, green and blue), which would be 1,080,000 calculations. In addition, most of the filtering operations (except noise) need to do a calculation on a "window" of adjoining pixels (2 on each side of each pixel), effectively multiplying the number of calculations by a further 5.

If possible, apply a filter once, and use the filtered image many times. As you can use miniwindows as image sources for other miniwindows, consider setting up a filtered image once, and then just copying it in when needed (eg. draw an elaborate background once, and then just copy in the result when needed).

See also FilterPixel which filters a single RGB code.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

eNoSuchWindow - no such miniwindow

eUnknownOption - filter mode not in the list above

eOK - completed OK

 View list of return code meanings

Lua example

-- Noise

WindowFilter (win, 0, 0, 0, 0, 1, 100)  -- colour noise in whole window - level 100

WindowFilter (win, 0, 0, 0, 0, 1, 50)   -- colour noise in whole window - level 50

WindowFilter (win, 0, 0, 0, 0, 2, 100)  -- monochrome noise in whole window - level 100

-- Blurring

WindowFilter (win, 10, 10, 90, 90, 3, 0) -- blur both directions

WindowFilter (win, 10, 10, 90, 90, 3, 1) -- blur horizontal

WindowFilter (win, 10, 10, 90, 90, 3, 2) -- blur vertical

-- Sharpening

WindowFilter (win, 10, 10, 90, 90, 4, 0) -- sharpen in both directions

-- Edge detection

WindowFilter (win, 10, 10, 90, 90, 5, 0) -- edge detect

-- Emboss

WindowFilter (win, 10, 10, 90, 90, 6, 0) -- emboss

-- Brightness

WindowFilter (win, 10, 10, 90, 90, 7, -100) -- lower by 100

WindowFilter (win, 10, 10, 90, 90, 7, 100) -- raise by 100

WindowFilter (win, 10, 10, 90, 90, 21, 0.5) -- halve the brightness

WindowFilter (win, 10, 10, 90, 90, 21, 2) -- double the brightness

-- Contrast

WindowFilter (win, 10, 10, 90, 90, 8, 0.5) -- reduce

WindowFilter (win, 10, 10, 90, 90, 8, 2) -- increase

WindowFilter (win, 10, 10, 90, 90, 8, 10) -- increase a lot

WindowFilter (win, 10, 10, 90, 90, 8, -2) -- make negative

-- Gamma

WindowFilter (win, 10, 10, 90, 90, 9, 0.3) -- brighter, lower contrast

WindowFilter (win, 10, 10, 90, 90, 9, 1.5)  -- darker, higher contrast

WindowFilter (win, 10, 10, 90, 90, 9, 5)   -- very dark and contrasty

Lua notes

You can use the following constants for the Operation argument:

miniwin.filter_noise = 1

miniwin.filter_monochrome_noise = 2

miniwin.filter_blur = 3

miniwin.filter_sharpen = 4

miniwin.filter_find_edges = 5

miniwin.filter_emboss = 6

miniwin.filter_brightness = 7

miniwin.filter_contrast = 8

miniwin.filter_gamma = 9

miniwin.filter_red_brightness = 10

miniwin.filter_red_contrast = 11

miniwin.filter_red_gamma = 12

miniwin.filter_green_brightness = 13

miniwin.filter_green_contrast = 14

miniwin.filter_green_gamma = 15

miniwin.filter_blue_brightness = 16

miniwin.filter_blue_contrast = 17

miniwin.filter_blue_gamma = 18

miniwin.filter_grayscale = 19

miniwin.filter_normal_grayscale = 20

miniwin.filter_brightness_multiply = 21

miniwin.filter_red_brightness_multiply = 22

miniwin.filter_green_brightness_multiply = 23

miniwin.filter_blue_brightness_multiply = 24

miniwin.filter_lesser_blur = 25

miniwin.filter_minor_blur = 26

miniwin.filter_average = 27

See Also ...

Topic

 MiniWindows

Functions

 FilterPixel (Performs a filtering operation on one pixel)

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowFilter)


WindowFont

Script function

world.WindowFont

 Read about scripting

Type

Method

Summary

Loads a font into a miniwindow

Prototype

long WindowFont(BSTR WindowName, BSTR FontId, BSTR FontName, double Size, BOOL Bold, BOOL Italic, BOOL Underline, BOOL Strikeout, short Charset, short PitchAndFamily);

 View list of data type meanings

Description

This loads the specified font into the miniwindow, and remembers it by the nominated "font id". The font id is later used for drawing in this font. You do not need to specify a colour, that is done when the text is actually drawn.

WindowName - the name of an existing miniwindow.

FontId - the font id to be associated with this particular font and size. If you are only planning to use one or two fonts you might call them "f1" and "f2". For more complex situations you might call them something like "heading", "body", "boldbody", "footer" etc.

If you use an existing FontId then the existing font is deleted and replaced by the one specified now.

FontName - the name of the font (for example, "Lucida Console", "Comic Sans MS", "Fixedsys"). If the FontName is an empty string (ie. name is "") and the Size is zero, then any existing font of the same FontId is deleted (and no new font is added).

If you are using Lua scripting, you can use the utils.getfontfamilies function to find which font names are actually installed.

Size - the size of the font in points

Bold - true if you want the bold version of the font

Italic - true if you want the italic version of the font

Underline - true if you want the underline version of the font

Strikeout - true if you want the strikeout version of the font

Charset - The character set wanted. Some possible values are:

0 - ANSI

1 - Default

2 - Symbol

Unless you have a reason otherwise, use 1 (default) which is the default value for Lua.

PitchAndFamily - the requested pitch and family

You can add together the following values:

Family

0 - Don't care

16 - Roman (variable width, serif, eg. Times Roman)

32 - Swiss (variable width, sans-serif, eg. Helvetica)

48 - Modern (fixed width, serif or sans-serif - eg. Courier)

64 - Script (cursive, etc.)

80 - Decorative (Old English, etc.)

Pitch

0 - Default

1 - Fixed pitch

2 - Variable pitch

8 - Mono font

Truetype

4 - Use Truetype font

A reasonable entry would be 0 - for don't care. Or, if you wanted a variable width, serif, truetype font, you could specify 20 (which is 16 + 4).

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

Return value

eNoSuchWindow - no such miniwindow

eCannotAddFont - cannot add it (perhaps font does not exist)

eOK - completed OK

 View list of return code meanings

Lua example

-- Trebuchet MS, 28 point, bold

WindowFont (win, "heading", "Trebuchet MS", 28, true, false, false, false)

Lua notes

You can use the following constants for the charset argument:

miniwin.font_charset_ansi = 0

miniwin.font_charset_default = 1

miniwin.font_charset_symbol = 2

You can use the following constants for the PitchAndFamily argument (these can be added together):

miniwin.font_family_any = 0

miniwin.font_family_roman = 16

miniwin.font_family_swiss = 32

miniwin.font_family_modern = 48

miniwin.font_family_script = 64

miniwin.font_family_decorative = 80

miniwin.font_pitch_default = 0

miniwin.font_pitch_fixed = 1

miniwin.font_pitch_variable = 2

miniwin.font_truetype = 4

miniwin.font_pitch_monospaced = 8

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowFont)


WindowFontInfo

Script function

world.WindowFontInfo

 Read about scripting

Type

Method

Summary

Returns information about a font

Prototype

VARIANT WindowFontInfo(BSTR WindowName, BSTR FontId, long InfoType);

 View list of data type meanings

Description

This returns information about a loaded font. You need to specify the name of the miniwindow, and the font id you used when loading the font.

Probably the most important item is number 1 - the height of the font. If you are drawing multiple lines of a particular font, you should add the font height to the "y" parameter of the rectangle, to move the pixel position down the window an appropriate amount.

WindowName - the name of an existing miniwindow.

FontId - the font id you used when you loaded the font.

InfoType - the information you want:

1: Height - Specifies the height (ascent + descent) of characters.

2: Ascent - Specifies the ascent (units above the base line) of characters

3: Descent - Specifies the descent (units below the base line) of characters.

4: Internal Leading - Specifies the amount of leading (space) inside the bounds set by the height. Accent marks and other diacritical characters may occur in this area. The designer may set this to zero.

5: External Leading - Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls. The designer may set this member to zero.

6: Average Character Width - Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.

7: Maximum Character Width - Specifies the width of the widest character in the font.

8: Weight - Specifies the weight of the font.

9: Overhang - Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

10: Digitized Aspect X	- Specifies the horizontal aspect of the device for which the font was designed.

11: Digitized Aspect Y	 - Specifies the vertical aspect of the device for which the font was designed. The ratio of the DigitizedAspectX and DigitizedAspectY is the aspect ratio of the device for which the font was designed.

12: First Character - Specifies the value of the first character defined in the font.

13: Last Character - Specifies the value of the last character defined in the font

14: Default Character - Specifies the value of the character to be substituted for characters not in the font.

15: Break Character - Specifies the value of the character that will be used to define word breaks for text justification.

16: Italic - Specifies an italic font if it is nonzero.

17: Underlined - Specifies an underlined font if it is nonzero.

18: Struck Out - Specifies a strikeout font if it is nonzero.

19: Pitch And Family - Specifies information about the pitch, the technology, and the family of a physical font.

20: Character Set - Specifies the character set of the font.

21: Name - Specifies the name of the font

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

Return value

The specified information about the font, as described above.

An EMPTY variant, if the font does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

WindowFontInfo (win, "f", 1)  --> get text height

Lua notes

Lua returns nil instead of a NULL or EMPTY variant.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowFontInfo)


WindowFontList

Script function

world.WindowFontList

 Read about scripting

Type

Method

Summary

Lists all fonts loaded into a miniwindow

Prototype

VARIANT WindowFontList(BSTR WindowName);

 View list of data type meanings

Description

This returns a list of all fonts loaded into this miniwindow. You could use this to find which fonts have been loaded, and then use WindowFontInfo to find information about each one.

WindowName - the name of the miniwindow to check for fonts.

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

Return value

If there are no fonts loaded then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the font ids of all the fonts. Use "ubound" to find the number of fonts in the list. You can then use "WindowFontInfo" to find details about each fonts.

Lua example

-- show all fonts

fonts = WindowFontList(win)

if fonts then

  for _, v in ipairs (fonts) do

    Note (v)

  end

end -- if any

Lua notes

Lua returns nil if there are no fonts.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowFontList)


WindowGetImageAlpha

Script function

world.WindowGetImageAlpha

 Read about scripting

Type

Method

Summary

Draws the alpha channel of an image into a miniwindow

Prototype

long WindowGetImageAlpha(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, long SrcLeft, long SrcTop);

 View list of data type meanings

Description

This copies the alpha channel of an image to the miniwindow, showing the alpha information as grayscale.

The alpha channel could be used when copying an image onto the miniwindow using the WindowMergeImageAlpha function.

Thus you could use WindowGetImageAlpha to create a scratch window (one not visible to the player) which holds the alpha information. This could then be turned into another image by using WindowImageFromWindow. This image is now available for use with WindowMergeImageAlpha to selectively copy the image to another miniwindow (this image would be used as the MaskId).

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw. (In the case of WindowGetImageAlpha you would probably never want to actually show the image, as it is just the alpha, or mask, channel).

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded (which must have an alpha channel - generally this means it will be 32 bits per pixel, which is 8 bits for each of red, green and blue, and 8 bits for the alpha information).

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

SrcLeft, SrcTop - the source offset in the original image (use 0,0 to get the whole image).

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage (or WindowLoadImageMemory), or the image does not have an alpha channel.

eOK - completed OK

 View list of return code meanings

Lua example

WindowGetImageAlpha (win, "im", 20, 20, 0, 0)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowGetImageAlpha)


WindowGetPixel

Script function

world.WindowGetPixel

 Read about scripting

Type

Method

Summary

Gets the colour of a single pixel in a miniwindow

Prototype

long WindowGetPixel(BSTR WindowName, long x, long y);

 View list of data type meanings

Description

Gets a single pixel colour from the miniwindow.

WindowName - the name of an existing miniwindow.

x, y - the location of the pixel (x is horizontal, y is vertical)

Note that after doing a WindowSetPixel, if you do a WindowGetPixel you will not necessarily get back the same value, particularly if the screen monitor resolution is set to 16 bit colour or less.

Return value

-1 if the pixel is out of the range of the window size.

-2 if the miniwindow does not exist.

Otherwise: The colour at that location as an RGB code.

Lua example

c = WindowGetPixel (win, 2, 3)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowGetPixel)


WindowGradient

Script function

world.WindowGradient

 Read about scripting

Type

Method

Summary

Draws a gradient in a rectangle

Prototype

long WindowGradient(BSTR WindowName, long Left, long Top, long Right, long Bottom, long StartColour, long EndColour, short Mode);

 View list of data type meanings

Description

Draws a gradient - that is a rectangle that gradually changes from the start colour to the end colour.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Left, Top, Right, Bottom - describes the rectangle to draw into.

StartColour - the colour to start the gradient (or, see below if you are using Mode 3)

EndColour - the colour to end the gradient.

Mode - the drawing direction. One of:

1 - horizontal - left to right

2 - vertical - top to bottom

3 - make a texture by xoring the x and y columns sequentially.

For Mode 3 (make a texture) - the StartColour has 3 components, red multiplier, green multiplier, blue multiplier. These are multiplied by the generated colour to give special effects to the generated texture. For example: 0x010203 would multiply the blue component by 1, the green component by 2 and the red component by 3.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow (either source or destination)

eUnknownOption - mode not one of the modes specified above

eOK - completed OK

 View list of return code meanings

Lua example

WindowGradient (win, 20, 110, 160, 180,

                ColourNameToRGB ("red"),

                ColourNameToRGB ("yellow"),

                1)  -- left to right

WindowGradient (win, 20, 20, 160, 100,

                ColourNameToRGB ("dodgerblue"),

                ColourNameToRGB ("lightsalmon"),

                2)  -- top to bottom

WindowGradient (win, 0, 0, 256, 256,

                0x010203,

                0,

                3)  -- XOR texture

Lua notes

You can use the following constants for the mode:

miniwin.gradient_horizontal = 1

miniwin.gradient_vertical = 2

miniwin.gradient_texture = 3

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowGradient)


WindowHotspotInfo

Script function

world.WindowHotspotInfo

 Read about scripting

Type

Method

Summary

Returns information about a hotspot

Prototype

VARIANT WindowHotspotInfo(BSTR WindowName, BSTR HotspotId, long InfoType);

 View list of data type meanings

Description

This returns information about a hotspot. You need to specify the name of the miniwindow, and the hotspot id you used when creating the hotspot.

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id you used when you created the hotspot.

InfoType - the information you want:

1: Rectangle: Left

2: Rectangle: Top

3: Rectangle: Right

4: Rectangle: Bottom

5: MouseOver function name

6: CancelMouseOver function name

7: MouseDown function name

8: CancelMouseDown function name

9: MouseUp function name

10: TooltipText

11: Cursor

12: Flags

13: MoveCallback function name  (from DragHandler call)

14: ReleaseCallback function name (from DragHandler call)

15: DragHandler flags (from DragHandler call)

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

Return value

The specified information about the hotspot, as described above.

An EMPTY variant, if the hotspot does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

WindowHotspotInfo(win, "hs1", 5)

Lua notes

Lua returns nil instead of a NULL or EMPTY variant.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowHotspotInfo)


WindowHotspotList

Script function

world.WindowHotspotList

 Read about scripting

Type

Method

Summary

Lists all hotspots installed into a miniwindow

Prototype

VARIANT WindowHotspotList(BSTR WindowName);

 View list of data type meanings

Description

This returns a list of all hotspots loaded into this miniwindow. You could use this to find which hotspots have been created, and then use WindowHotspotInfo to find information about each one.

WindowName - the name of the miniwindow to check for hotspots.

For more information, see:

http://www.gammon.com.au/mushclient/mw_hotspots.htm

Return value

If there are no hotspots installed then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the hotspot ids of all the hotspots. Use "ubound" to find the number of hotspots in the list. You can then use "WindowHotspotList" to find details about each hotspot.

Lua example

-- show all hotspots

hotspots = WindowHotspotList(win)

if hotspots then

  for _, v in ipairs (hotspots) do

    Note (v)

  end

end -- if any

Lua notes

Lua returns nil if there are no hotspots.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowHotspotList)


WindowHotspotTooltip

Script function

world.WindowHotspotTooltip

 Read about scripting

Type

Method

Summary

Changes the tooltip text for a hotspot in a miniwindow

Prototype

long WindowHotspotTooltip(BSTR WindowName, BSTR HotspotId, BSTR TooltipText);

 View list of data type meanings

Description

This function lets you change the tooltip text for an existing hotspot.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id associated with this particular hotspot. Hotspot IDs are case-sensitive.

TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text.

Return value

eNoSuchWindow - no such miniwindow

eHotspotNotInstalled - no such hotspot

eOK - completed OK

 View list of return code meanings

Lua example

WindowHotspotTooltip (win, "hs1",  "Click here to be cured")

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowHotspotTooltip)


WindowImageFromWindow

Script function

world.WindowImageFromWindow

 Read about scripting

Type

Method

Summary

Creates an image from another miniwindow

Prototype

long WindowImageFromWindow(BSTR WindowName, BSTR ImageId, BSTR SourceWindow);

 View list of data type meanings

Description

This uses an existing miniwindow's offscreen bitmap, to make an image that can be loaded into another miniwindow. This lets you set up offscreen windows (that you may never plan to actually show with WindowShow) as "work areas" for creating text or images, that can be loaded or blended into other windows.

WindowName - the name of an existing miniwindow.

ImageId - the image id to store its image under.

SourceWindow - the miniwindow name that is the source of the image.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

eNoSuchWindow - no such miniwindow (either source or destination)

eOK - completed OK

 View list of return code meanings

Lua example

-- create another window

WindowCreate ("map2window", 0, 0, 150, 150, 4, 0, 0x000000) ) -- top left corner

-- pull in map window as "map" from mapping plugin

WindowImageFromWindow("map2window", "map", "86810b755a33169f0f1d9585")

-- draw our small map into "map2" window

WindowDrawImage ("map2window", "map", 0, 0, 0, 0, 2);

-- show smaller map

WindowShow ("map2window", true)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowImageFromWindow)


WindowImageInfo

Script function

world.WindowImageInfo

 Read about scripting

Type

Method

Summary

Returns information about an image

Prototype

VARIANT WindowImageInfo(BSTR WindowName, BSTR ImageId, long InfoType);

 View list of data type meanings

Description

This returns information about a loaded image. You need to specify the name of the miniwindow, and the image id you used when loading the image.

WindowName - the name of an existing miniwindow.

ImageId - the image id you used when you loaded the image.

InfoType - the information you want:

1: Type - Specifies the bitmap type.

2: Width - Specifies the width, in pixels, of the bitmap.

3: Height - Specifies the height, in pixels, of the bitmap.

4: WidthBytes - Specifies the number of bytes in each scan line.

5: Planes - Specifies the count of color planes.

6: BitsPixel - Specifies the number of bits required to indicate the color of a pixel.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

The specified information about the image, as described above.

An EMPTY variant, if the image does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

WindowImageInfo(win, "im1", 6)

Lua notes

Lua returns nil instead of a NULL or EMPTY variant.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowImageInfo)


WindowImageList

Script function

world.WindowImageList

 Read about scripting

Type

Method

Summary

Lists all images installed into a miniwindow

Prototype

VARIANT WindowImageList(BSTR WindowName);

 View list of data type meanings

Description

This returns a list of all images loaded into this miniwindow. You could use this to find which images have been loaded, and then use WindowImageInfo to find information about each one.

WindowName - the name of the miniwindow to check for images.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

If there are no images installed then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the image ids of all the hotspots. Use "ubound" to find the number of images in the list. You can then use "WindowImageInfo" to find details about each image.

Lua example

-- show all images

images = WindowImageList(win)

if images then

  for _, v in ipairs (images) do

    Note (v)

  end

end -- if any

Lua notes

Lua returns nil if there are no images.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowImageList)


WindowImageOp

Script function

world.WindowImageOp

 Read about scripting

Type

Method

Summary

Draws an ellipse, rectangle or round rectangle, filled with an image

Prototype

long WindowImageOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long PenColour, long PenStyle, long PenWidth, long BrushColour, BSTR ImageId, long EllipseWidth, long EllipseHeight);

 View list of data type meanings

Description

This draws an ellipse, rectangle, round rectangle, controlled by the Action parameter. The specified shape is filled with a previously-loaded image.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of shape to draw, as follows:

1 = Ellipse

2 = Rectangle

3 = Round Rectangle

Left, Top, Right, Bottom - describes the rectangle into which the shape must fit.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the colour used for drawing the background, when displaying monochrome bitmaps.

ImageId - an image id that you have loaded.

EllipseWidth, EllipseHeight - the dimensions of the ellipse in the corner of a round rectangle, if applicable.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage

ePenStyleNotValid - invalid pen style

eUnknownOption - drawing mode not in list above

eOK - completed OK

 View list of return code meanings

Lua example

WindowImageOp (win, 1, 20, 20, 150, 150,    -- circle

              ColourNameToRGB("blue"), 0, 2,

              ColourNameToRGB("cyan"), "im")

WindowImageOp (win, 2, 0, 0, 0, 0,    -- rectangle

              ColourNameToRGB("blue"), 5, 1,

              ColourNameToRGB("cyan"), "im")

WindowImageOp (win, 3, 20, 20, 160, 160,    -- round rectangle

              ColourNameToRGB("blue"), 0, 3,

              ColourNameToRGB("cyan"), "im",

              20, 20)

Lua notes

You can use the following constants for the action:

miniwin.image_fill_ellipse = 1

miniwin.image_fill_rectangle = 2

miniwin.image_fill_round_fill_rectangle = 3

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowImageOp)


WindowInfo

Script function

world.WindowInfo

 Read about scripting

Type

Method

Summary

Returns information about a miniwindow

Prototype

VARIANT WindowInfo(BSTR WindowName, long InfoType);

 View list of data type meanings

Description

This returns information about a particular miniwindow. You might use this to find where the window is on the screen, what its size is, whether it is visible, and so on.

WindowName - the name of an existing miniwindow.

InfoType - the information you want:

1: Left (from WindowCreate)

2: Top (from WindowCreate)

3: Width

4: Height

5: Show flag

6: Is it hidden right now?

7: Layout position code

8: Flags

9: Background colour

10: Where it is right now: left

11: Where it is right now: top

12: Where it is right now: right

13: Where it is right now: bottom

14: Where mouse last was (mouse down, mouse up or move) - X position - relative to miniwindow

15: Where mouse last was (mouse down, mouse up or move) - Y position - relative to miniwindow

16: Incremented each time items 14/15 are updated.

17: Where mouse was (during drag operation) - X position - relative to output window

18: Where mouse was (during drag operation) - y position - relative to output window

19: Hotspot ID of the hotspot currently being moused-over (empty string if none)

20: Hotspot ID of the hotspot currently being moused-down in (empty string if none)

21: Date/time the miniwindow was installed.

22: The Z-Order of the miniwindow.

23: The Plugin ID of the plugin that created this miniwindow (empty string if no plugin)

InfoType 10 to 13 are where the auto positioning last placed the window (the last time the main screen was refreshed).

The "show" flag is whether you want the window shown. Infotype 6 is whether it had to be temporarily hidden. This only applies to position codes 5, 7, 9, 11. The window will thus be visible if:

* The Show flag is true (Infotype 5)

* The "Is it hidden right now" flag is false (Infotype 6)

* It is actually positioned somewhere it can be seen

* Another window is not on top of it

The mouse position (info items 14 and 15) are updated each time a mouse-down, mouse-up, or mouse-move event is processed by a miniwindow. When this happens, item 16 is incremented. This will eventually "wrap around" and become negative once it is incremented 2,147,483,648 times.

The intention here is that if item 16 changes (whether up or down) then you know a new mouse coordinate has been recorded for this miniwindow.

The mouse position  (for info items 14 and 15) is relative to the start of the miniwindow, whatever that is. You could use this to create a pop-up menu at the point at which the mouse was clicked.

If item 20 is not the empty string, then the mouse is currently "captured" by the nominated hotspot.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Return value

The specified information about the window, as described above.

An EMPTY variant, if the window does not exist.

A NULL variant if the InfoType is not a valid type.

Lua example

WindowInfo (win, 4) --> get height

Lua notes

Lua returns nil instead of a NULL or EMPTY variant.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowInfo)


WindowLine

Script function

world.WindowLine

 Read about scripting

Type

Method

Summary

Draws a line in a miniwindow

Prototype

long WindowLine(BSTR WindowName, long x1, long y1, long x2, long y2, long PenColour, long PenStyle, long PenWidth);

 View list of data type meanings

Description

This draws a line from x1,y1 to x2,y2 with the designated pen.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

x1, y2 - the starting point for the line.

x2, y2 - the ending point for the line (note: the x2, y2 point is taken literally, zero or negative numbers have no special significance, as at version 4.38 of MUSHclient).

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eOK - completed OK

 View list of return code meanings

Lua example

WindowLine (win, 20, 20, 80, 80, ColourNameToRGB ("blue"), 0, 2)

Lua notes

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowLine)


WindowList

Script function

world.WindowList

 Read about scripting

Type

Method

Summary

Lists all miniwindows

Prototype

VARIANT WindowList();

 View list of data type meanings

Description

This returns a list of all miniwindows created for this world. You could use this to find which windows have been created, and then use WindowInfo to find information about each one.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Return value

If there are no miniwindows then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the miniwindows. Use "ubound" to find the number of miniwindows in the list. You can then use "WindowInfo" to find details about each miniwindow.

Lua example

-- show all windows

windows = WindowList()

if windows then

  for _, v in ipairs (windows) do

    Note (v)

  end

end -- if any

Lua notes

Lua returns nil if there are no miniwindows.

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowList)


WindowLoadImage

Script function

world.WindowLoadImage

 Read about scripting

Type

Method

Summary

Loads an image into a miniwindow from a disk file

Prototype

long WindowLoadImage(BSTR WindowName, BSTR ImageId, BSTR FileName);

 View list of data type meanings

Description

This loads the specified image into the miniwindow, and remembers it by the nominated "image id". The image id is later used for drawing this image. Loading does not draw it, it simply reads it from disk ready for drawing later.

Also see below in the Lua notes for WindowLoadImageMemory which loads an image loaded into memory.

WindowName - the name of an existing miniwindow.

ImageId - the image id to be associated with this particular image.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type. If the filename is the empty string (ie. "") then any existing image matching the ImageId is deleted.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

If the loaded image is a PNG file, then it will have 24 bits per pixel if it does not have an alpha channel, and 32 bits per pixel if it has an alpha channel. You can use WindowImageInfo with selector 6 to find the number of bits per pixel of the loaded image.

Return value

eNoSuchWindow - no such miniwindow

eFileNotFound - specified file was not found

eUnableToLoadImage - can't load image - perhaps it is not a BMP or PNG file

eOK - completed OK

 View list of return code meanings

Lua example

WindowLoadImage (win, "im1", "C:/program files/mushclient/leaf.bmp")

WindowLoadImage (win, "im2", "C:/program files/mushclient/background.png")

Lua notes

From version 4.42 onwards, Lua also supports WindowLoadImageMemory which loads an image file loaded into a memory buffer.

In this case the third argument is the memory buffer, not the file name.

local f = assert (io.open ("sword.png", "rb"))

local image_data = f:read ("*a")  -- read all of it

f:close ()  -- close it

WindowLoadImageMemory (win, "im", image_data) -- load image from memory

WindowDrawImage (win, "im", 20, 20, 0, 0, 1)  -- draw it

For WindowLoadImageMemory only PNG files are supported, not BMP ones.

WindowLoadImageMemory also supports an optional fourth argument. If true, the blue channel is swapped with the alpha channel.  Thus, code like below would load the image  into "ima", and then show it in the miniwindow, showing only the alpha mask:

WindowLoadImageMemory (win, "ima", image_data, true)

WindowBlendImage (win, "ima", 0, 0, 0, 0, 59, 1)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowLoadImage)


WindowMenu

Script function

world.WindowMenu

 Read about scripting

Type

Method

Summary

Creates a pop-up menu inside a miniwindow

Prototype

BSTR WindowMenu(BSTR WindowName, long Left, long Top, BSTR Items);

 View list of data type meanings

Description

This creates a pop-up menu inside a miniwindow. This is intended to let you click on an item (for example, a piece of inventory), and select "take/drop/equip/wield" and so on.

The window must exist, and be visible, or an empty string is returned.

WindowName: The name of an existing miniwindow

Left: The X position inside the miniwindow

Top: The Y position inside the miniwindow

Items: A string containing the menu items to be displayed, see below.

The X and Y position must be inside the miniwindow (ie. not negative, and not exceeding the miniwindow's defined width and height). Otherwise, an empty string is returned.

You can use WindowInfo (win, 14) and WindowInfo (win, 15) to find where the mouse was last clicked inside this miniwindow.

The Items parameter is a string, containing the menu items to be displayed, separated by the "|" character. Leading and trailing spaces are removed from each item.

For example:  Item = "^Sword | - | Wield | Equip | - |  Take | Drop "

There must be at least one item,  or an empty string is returned.

An item which is empty, or consisting of the character "-" is displayed as a menu separator (horizontal line).

An item which commences with the "^" character is displayed disabled (grayed out, and it cannot be selected). The "^" character is removed.

An item which commences with the "+" character is displayed checked (with a tick mark next to it). The "+" character is removed.

Items may have both a + and ^ in front of them, in either order.

An item which commences with the ">" character represents a nested menu. Subsequent items until a "<" character are in the nested menu.

An item which commences with the "<" character ends a nested menu.

You can display a maximum of 100 selectable items. This does not count nested menus items, disabled items, and separator lines. That is, there can be a maximum of 100 items which can be actually chosen by the player.

The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned.

In the above example, a menu would be shown like this:

Sword (grayed out)

-----

Wield

Equip

-----

Take

Drop

Thus the return value would be one of:

"" - menu dismissed

"Wield", "Equip", "Take", or "Drop"

Note that the leading and trailing spaces around the items have been removed in the return value.

WARNING - we reserve non alpha-numeric characters in the first position of each item for future expansion. For example, perhaps in future versions "*Equip" might be used to tick the Equip item.

SUGGESTION - we strongly recommend that, if you are creating a menu in response to a mouse-click, you do it on the "mouse up" rather than "mouse down".

The reason for this is that MUSHclient tracks mouse-down events and their corresponding mouse-up events, in order to call the appropriate hotspot routines (mouse-down, mouse-up, mouse-down cancel).

However if you call WindowMenu in response to a mouse-down, the next mouse-up is "swallowed" up by the menu handler, and thus MUSHclient doesn't "see" it. The end result is that MUSHclient thinks the mouse is down, when it is in fact up. This gets the hotspot events out of synchronization, and then subsequent things like mouse-overs are not processed correctly.

So, for best results, draw a menu after a mouse-up. This if in fact what most Windows programs do, if you look carefully. In general, programs don't respond when you click down on the mouse, the action response happens when you let go (the mouse-up event).

Example of nested menus:

Items = "Take | Drop | >Eat | With Fork | With Hands | < | >Emote | Smile | Laugh "

This would display:

Take

Drop

Eat ->

..With Fork

..With Hands

Emote ->

..Smile

..Laugh

(Where Eat and Emote are nested menus)

If the first character of the entire Items string is the "!" character, then the function returns the selected item number rather than the selected string. It still returns an empty string if nothing is selected. The "!" is then removed and the rest of the string treated in the usual way (so you could then start a submenu, for example).

This lets you distinguish between multiple identical items in submenus.

Only items that generate "active" menu elements are counted. That is, divider lines, grayed-out items, and sub-menus are not counted. The first item is item 1.

For example:

Items = "!Take |-| ^Drop | >Eat | Fork | Hands | < | >Emote | Smile | Laugh "

In this case we would get:

Take: 1

Divider line: (can't be selected)

Drop: (can't be selected)

Eat -> Fork: 2

Eat -> Hands: 3

Emote -> Smile: 4

Emote -> Laugh: 5

Cancelled: empty string

If the first character of the entire Items string is the "~" character, then the menu alignment is specified by the next two characters. The "~xx" characters are then removed and the rest of the string treated in the usual way (so you could then start a submenu, for example).

The two characters following the "~" are the horizontal and vertical alignments, as follows:

Horizontal: L, C or R (left, centre, right)

Vertical: T, C or B (top, centre, bottom)

Default is top left (so the menu aligns to the specified point and appears on the right and underneath). That is, top left is where the menu starts. The letters are not case-sensitive. Anything other than those letters will be ignored.

For example:

Items = "~RBTake | Drop"   -- align cursor on right and bottom of point.

If you want to use both "!" and "~" then use "!" first as that is checked for and then removed from the string. Then it checks for "~" next. After that the normal menu processing takes place.

Summary of special characters in the first column:

! : return numeric result (only in first position of entire string)

~ : specify menu alignment (only in first position of entire string, or after "!")

- : separator line

^ : grayed-out item

+ : checked (ticked) item

> : start of nested menu (rest of line is nested menu title)

< : end of nested menu (rest of line is ignored)

Nested menus can be further nested.

Nested menus added in version 4.52. Numeric results added in version 4.65.

Checked items added in version 4.71. Menu alignment added in version 5.05.

Return value

If there was an error condition as described above, the empty string.

If the menu was dismissed, or no item selected, the empty string.

Otherwise, the text of the selected item, with leading and trailing spaces removed.

However if the first character of the Items string is the "!" character then, if the menu was not cancelled, a number is returned, starting at 1, being the item number of the selected item. Only active items (ones which can be selected) are counted.

Lua example

result = WindowMenu (win,

  WindowInfo (win, 14),  -- x

  WindowInfo (win, 15),   -- y

  "^Sword of Fire|-|Wield|Drop|Wear")

if result ~= "" then

  Send (result .. " 'Sword of Fire' ")

end -- if

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 Menu (Creates a pop-up menu inside the command window)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowMenu)


WindowMergeImageAlpha

Script function

world.WindowMergeImageAlpha

 Read about scripting

Type

Method

Summary

Merges an image into a miniwindow based on an alpha mask

Prototype

long WindowMergeImageAlpha(BSTR WindowName, BSTR ImageId, BSTR MaskId, long Left, long Top, long Right, long Bottom, short Mode, double Opacity, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

 View list of data type meanings

Description

This merges the previously-loaded image identified by ImageId onto the miniwindow, based on the opacity of the mask MaskId. The mask must be large enough to cover the requested area in the blended image.

One method of setting up a mask would be to use the WindowGetImageAlpha function to obtain the alpha information from an image. Alternatively you might have the alpha information in a separate image file.

Each colour (red/green/blue) in the mask is individually considered when merging each pixel. If the mask is white (ie. 255) for that colour, then the blended image is used. If the mask is black (ie. 0) then the base image is preserved. In between, the blended image is used to the extent of the value (for example, 128 would be a 50% blend).

You can use a mask with a soft border (eg. by blurring it) to make a soft transition between the loaded image and the existing contents of the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have previously loaded.

MaskId - an image id for the mask, which has been previously loaded.

Left, Top, Right, Bottom - describes the destination rectangle. The blend image is merged with the contents of this rectangle to produce the blended result.

Mode - the blending method.

0 = straight blend

1 = transparent blend - the pixel at 0,0 in the ImageId image will be taken as the transparency colour.

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the merged image. An opacity of 1 means the merge is fully applied. An opacity of 0.5 means the masked, merged image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

When blending, whichever rectangle is smaller is the one used for the width and height of the operation (the destination rectangle or the source rectangle).

Return value

eBadParameter - Opacity not in range 0 to 1, or mask not large enough

eImageNotInstalled - Either the blend image or the mask image is not installed

eNoSuchWindow - No such miniwindow

eUnknownOption - Mode not in list above

eOK - success

 View list of return code meanings

Lua example

WindowMergeImageAlpha (win, "castle", "mask",

                       0, 0, 0, 0,   -- full image

                       1, 1,            -- use transparency, 100% opacity

                       0, 0, 0, 0)  -- source offset

Lua notes

You can use the following constants for the mode:

miniwin.merge_straight = 0

miniwin.merge_transparent = 1

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowMergeImageAlpha)


WindowMoveHotspot

Script function

world.WindowMoveHotspot

 Read about scripting

Type

Method

Summary

Moves a hotspot in a miniwindow

Prototype

long WindowMoveHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom);

 View list of data type meanings

Description

Moves a hotspot in a miniwindow. The miniwindow must already exist. The hotspot must already exist.

This lets you reposition a hotspot (for example, if the window is resized).

For more information about hotspots see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id of this particular hotspot. Hotspot IDs are case-sensitive.

Left, Top, Right, Bottom - describes the new hotspot rectangle.

Return value

eNoSuchWindow - no such miniwindow

eHotspotNotInstalled - this hotspot has not been defined for this window

eOK - completed OK

 View list of return code meanings

Lua example

WindowMoveHotspot(win, "hs1",

                 20, 20, 80, 40)   -- new rectangle

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowMoveHotspot)


WindowPolygon

Script function

world.WindowPolygon

 Read about scripting

Type

Method

Summary

Draws a polygon in a miniwindow

Prototype

long WindowPolygon(BSTR WindowName, BSTR Points, long PenColour, long PenStyle, long PenWidth, long BrushColour, long BrushStyle, BOOL Close, BOOL Winding);

 View list of data type meanings

Description

This draws a polygon (series of straight lines) connecting the specified points, with the designated pen and filled with the designated brush.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Points - a string consisting of pairs of numbers, one for each point, in the format x1,y1,x2,y2 ...

For example: "20,50,180,50" would specify two points, one at 20,50 and one at 180,50.

You must have at least 2 points (the start and end), which is 4 numbers. The number of numbers in the string must be even (divisible by two), as it takes a pair of numbers to specify one point.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)

1 - dash: -------

2 - dot: .......

3 - dashdot: _._._._

4 - dashdotdot: _.._.._

5 - null (no pen)

6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)

0x0100 - square ends  (256)

0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)

0x1000 - bevel joins  (4096)

0x2000 - miter joins  (8192)

PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the RGB colour for this brush

BrushStyle - what style of brush to use:

0: solid (filled with a solid colour)

1: null (not filled)

2: hatch: horizontal

3: hatch: vertical

4: hatch: forwards diagonal

5: hatch: backwards diagonal

6: hatch: cross

7: hatch: diagonal cross

8: fine pattern

9: medium pattern

10: coarse pattern

11: waves - horizontal

12: waves - vertical

BrushColour, Brushstyle - the brush colour and style as described at the top of this page.

Close - if true, the polygon is closed by connecting the last point to the first one, if necessary

Winding - if true the polygon is filled using the "winding" algorithm, if false it is filled using the "alternate" algorithm.

When the polygon-filling mode is "alternate", the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on. This mode is the default.

When the polygon-filling mode is "winding", the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, a count is incremented. When the line passes through a counterclockwise line segment, the count is decremented. The area is filled if the count is nonzero when the line reaches the outside of the figure.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eBrushStyleNotValid - invalid brush style

eInvalidNumberOfPoints - must have at least 2 points (4 numbers) and the number of numbers must be divisible by 2

eOK - completed OK

 View list of return code meanings

Lua example

WindowPolygon (win, "20,50,180,50,180,20,230,70,180,120,180,90,20,90",

                        ColourNameToRGB("cyan"), 0, 3,   -- pen (solid, width 3)

                        ColourNameToRGB("yellow"), 0,    -- brush (solid)

                        true,    -- fill

                        false)   -- alternate fill

Lua notes

You can use the following constants for the pen style:

miniwin.pen_solid = 0

miniwin.pen_dash = 1

miniwin.pen_dot = 2

miniwin.pen_dash_dot = 3

miniwin.pen_dash_dot_dot = 4

miniwin.pen_null = 5

miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)

miniwin.pen_join_round = 0

miniwin.pen_join_bevel = 4096

miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)

miniwin.pen_endcap_round = 0

miniwin.pen_endcap_square = 256

miniwin.pen_endcap_flat = 512

You can use the following constants for the brush style:

miniwin.brush_solid = 0

miniwin.brush_null = 1

miniwin.brush_hatch_horizontal = 2

miniwin.brush_hatch_vertical = 3

miniwin.brush_hatch_forwards_diagonal = 4

miniwin.brush_hatch_backwards_diagonal = 5

miniwin.brush_hatch_cross = 6

miniwin.brush_hatch_cross_diagonal = 7

miniwin.brush_fine_pattern = 8

miniwin.brush_medium_pattern = 9

miniwin.brush_coarse_pattern = 10

miniwin.brush_waves_horizontal = 11

miniwin.brush_waves_vertical = 12

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowPolygon)


WindowPosition

Script function

world.WindowPosition

 Read about scripting

Type

Method

Summary

Moves a miniwindow

Prototype

long WindowPosition(BSTR WindowName, long Left, long Top, short Position, long Flags);

 View list of data type meanings

Description

This lets you move a miniwindow. This is only really useful if you are setting the "Absolute location" flag when creating it. In this case, if you notice the output window has been resized, you may want to resposition the window, without having to re-create it, and redraw all its contents.

The output window is scheduled for a redraw if this function is successful.

WindowName - the name of an existing miniwindow.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Position - a number indicating where you want the window positioned on the screen. Whenever the screen is resized or redrawn the contents of the window are drawn in the requested position:

0 = strech to output view size

1 = stretch with aspect ratio

2 = strech to owner size

3 = stretch with aspect ratio

4 = top left

5 = center left-right at top

6 = top right

7 = on right, center top-bottom

8 = on right, at bottom

9 = center left-right at bottom

10 = on left, at bottom

11 = on left, center top-bottom

12 = centre all

13 = tile

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events.

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow (with WindowCreate).

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Return value

eNoSuchWindow - no such miniwindow

eOK - success

 View list of return code meanings

Lua notes

You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0

miniwin.pos_stretch_to_view_with_aspect = 1

miniwin.pos_stretch_to_owner = 2

miniwin.pos_stretch_to_owner_with_aspect = 3

miniwin.pos_top_left = 4

miniwin.pos_top_center = 5

miniwin.pos_top_right = 6

miniwin.pos_center_right = 7

miniwin.pos_bottom_right = 8

miniwin.pos_bottom_center = 9

miniwin.pos_bottom_left = 10

miniwin.pos_center_left = 11

miniwin.pos_center_all = 12

miniwin.pos_tile = 13

You can use the following constants for the flags:

miniwin.create_underneath = 1

miniwin.create_absolute_location = 2

miniwin.create_transparent = 4

miniwin.create_ignore_mouse = 8

miniwin.create_keep_hotspots = 16

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowPosition)


WindowRectOp

Script function

world.WindowRectOp

 Read about scripting

Type

Method

Summary

Draws a rectangle in a miniwindow

Prototype

long WindowRectOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long Colour1, long Colour2);

 View list of data type meanings

Description

This draws a rectangle in various styles, controlled by the Action parameter.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of rectangle to draw, as follows:

1 = Frame by a single pixel wide line in Colour1

2 = Fill the entire rectangle by Colour1

3 = InvertRect - the colour on the miniwindow inside that rectangle is inverted

4 = Draw a "3D-style" rectangle in two colours, a single pixel wide (Colour1 is top and left edge colour, Colour2 is bottom and right edge colour)

5 = Draw Edge (draws a 3d-style edge with optional fill)

6 = Flood Fill Border (fills to border specified by Colour1) - the filling commences at the pixel designated by Left, Top and continues until it runs out of pixels that colour. The fill colour is specified by Colour2.

7 = Flood Fill Surface (fills while on surface specified by Colour1) - the filling commences at the pixel designated by Left, Top and continues until it is on pixels that colour. The fill colour is specified by Colour2.

Left, Top, Right, Bottom - describes the rectangle to be drawn.

Colour1 - the colour to draw the rectangle in (or fill it). For Action 5, this must be one of:

5 : Raised

6 : Etched

9 : Bump

10 : Sunken

Colour2 - the colour used by Action 4 for the bottom and right edge. Also it is the colour used for flood filling (Actions 6 and 7). For Action 5, this is:

0x03 (3) top left

0x06 (6) top right

0x09 (9) bottom left

0x0c (12) bottom right

0x0f (15) rect

Diagonal lines:

0x13 (19) diagonal - end top left

0x16 (22) diagonal - end top right

0x19 (25) diagonal - end bottom left

0x1c (28) diagonal - end bottom right

For Action 5 you can also add in the following values to modify the behaviour of the drawn rectangle:

0x0800 - Fill in the middle

0x1000 - For softer buttons

0x4000 - For flat rather than 3D borders

0x8000 - For monochrome borders

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

Return value

eNoSuchWindow - no such miniwindow

eUnknownOption - Action not in list above

eBadParameter - edge parameter invalid

eOK - completed OK

 View list of return code meanings

Lua example

WindowRectOp (win, 1, 20, 20, 70, 70, ColourNameToRGB("blue"))  -- outline

WindowRectOp (win, 2, 50, 20, 80, 80, ColourNameToRGB("green"))  -- filled

WindowRectOp (win, 3, 5, 5, 90, 90, 0)   -- invert

WindowRectOp (win, 4, 50, 30, 70, 70, ColourNameToRGB("springgreen"), ColourNameToRGB("green"))

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15)  -- raised, not filled

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800)  -- raised, filled

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800 + 0x1000)  -- raised, filled, softer

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800 + 0x1000 + 0x4000)  -- raised, filled, softer, flat

WindowRectOp (win, 5, 30, 30, 70, 70, 6, 15 + 0x800)  -- etched, filled

Lua notes

You can use the following constants for the action:

miniwin.rect_frame = 1

miniwin.rect_fill = 2

miniwin.rect_invert = 3

miniwin.rect_3d_rect = 4

miniwin.rect_draw_edge = 5

miniwin.rect_flood_fill_border = 6

miniwin.rect_flood_fill_surface = 7

You can use the following constants for the Colour1 parameter (argument 7) for action 5 (rect_draw_edge):

miniwin.rect_edge_raised = 5

miniwin.rect_edge_etched = 6

miniwin.rect_edge_bump = 9

miniwin.rect_edge_sunken = 10

You can use the following constants for the Colour2 parameter (argument 8) for action 5 (rect_draw_edge):

miniwin.rect_edge_at_top_left = 3

miniwin.rect_edge_at_top_right = 6

miniwin.rect_edge_at_bottom_left = 9

miniwin.rect_edge_at_bottom_right = 12

miniwin.rect_edge_at_all = 15

miniwin.rect_diagonal_end_top_left = 19

miniwin.rect_diagonal_end_top_right = 22

miniwin.rect_diagonal_end_bottom_left = 25

miniwin.rect_diagonal_end_bottom_right = 28

You can add in these additional constants to the Colour2 parameter (argument 8) for action 5 (rect_draw_edge):

miniwin.rect_option_fill_middle = 2048

miniwin.rect_option_softer_buttons = 4096

miniwin.rect_option_flat_borders = 16384

miniwin.rect_option_monochrom_borders = 32768

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowRectOp)


WindowResize

Script function

world.WindowResize

 Read about scripting

Type

Method

Summary

Resizes a miniwindow

Prototype

long WindowResize(BSTR WindowName, long Width, long Height, long BackgroundColour);

 View list of data type meanings

Description

This resizes an existing miniwindow of the given name.

If the new size is larger than the existing size the BackgroundColour is used to fill any newly exposed area.

Any existing contents of the miniwindow are copied to the top-left corner of the new window.

The output window is not automatically redrawn. Call Redraw or WindowShow to cause the new size to become visible.

Any existing hotspots, images, and fonts are preserved. All other window parameters for this miniwindow are unchanged.

PARAMETERS:

WindowName - the name of an existing miniwindow. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Width, Height - the width and height of the window, in pixels. The minimum size is 0, 0.

BackgroundColour - this is the RGB code for the colour is used to replace any pixels which are now visible, which were not previously (if the new size is larger than the old one).

Return value

eNoNameSpecified - miniwindow name must be specified

eBadParameter - width or height less than zero

eOK - success

 View list of return code meanings

Lua example

WindowResize ("inventory", 300, 400, ColourNameToRGB ("red"))  -- resize window to 300 x 400

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowResize)


WindowScrollwheelHandler

Script function

world.WindowScrollwheelHandler

 Read about scripting

Type

Method

Summary

Adds a scroll-wheel handler to a miniwindow hotspot

Prototype

long WindowScrollwheelHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback);

 View list of data type meanings

Description

Adds a scroll-wheel handler callback to the nominated hotspot.

If:

* The user moves the scroll wheel over a miniwindow hotspot; and

* There is a MoveCallback function defined (by using this function)

... then the callback function is called.

To cancel a scroll wheel handler, just set the function name to the empty string, eg.

WindowScrollwheelHandler(win, "hs1", "")

The callback function should look like this:

function wheel_move (flags, hotspot_id)

  if bit.band (flags, 0x100) ~= 0 then

    -- wheel scrolled down (towards you)

  else

    -- wheel scrolled up (away from you)

  end -- if

  return 0  -- needed for some languages

end -- wheel_move

The flags parameter is a bit mask as follows:

0x01 - Shift key down

0x02 - Control key down

0x04 - Alt key down

0x100 - Scroll wheel scrolled down (towards you)

In Lua you can use bit.band (as illustrated above) to test individual flags. In other languages you can use bit manipulation tests to check the flags. For example, in VBscript if flags is >= 256 then the mouse wheel was scrolled towards you.

The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

WARNING: The callbacks is not a function, but the name of a function. That is, it should be supplied as a string argument. The supplied name is looked up in the script space at the appropriate time.

Return value

eNoSuchWindow - no such miniwindow

eHotspotNotInstalled - no such hotspot

eInvalidObjectLabel - the script function is not a valid function name

eHotspotPluginChanged - the plugin is not the same one as used before for hotspots

eOK - completed OK

 View list of return code meanings

Lua example

function wheel_move (flags, hotspot_id)

 if bit.band (flags, 0x100) ~= 0 then

    -- wheel scrolled down (towards you)

  else

    -- wheel scrolled up (away from you)

  end -- if

  return 0  -- needed for some languages

end -- wheel_move

WindowScrollwheelHandler(win, "hs1", "wheel_move")

Lua notes

The handler function name can be omitted and default to the empty string (ie. no function).

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowScrollwheelHandler)


WindowSetPixel

Script function

world.WindowSetPixel

 Read about scripting

Type

Method

Summary

Sets a single pixel in a miniwindow to the specified colour

Prototype

long WindowSetPixel(BSTR WindowName, long x, long y, long Colour);

 View list of data type meanings

Description

Sets a single pixel in the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

x, y - the location of the pixel (x is horizontal, y is vertical)

Colour - the colour to set the pixel to. Note that the pixel which appears in the window may not necessarily be the exact one you chose, depending on the colour depth of your monitor. For example, for 16-bit colour depth, only 5 bits are used for each of red/green/blue, and thus a colour that cannot be exactly expressed in 5 bits will be rounded to the nearest colour.

Warning - although setting individual pixels is reasonably fast, if you need to set a lot (for example, to draw a line or a box), it would be much faster to use the appropriate dedicated function (such as WindowLine). This is because to draw boxes and lines, especially large ones, or filled ones, would take many, many calls to WindowSetPixel to achieve the same result.

Return value

eNoSuchWindow - no such miniwindow

eOK - success

 View list of return code meanings

Lua example

for x = 1, 360 do

  local y = math.sin (math.rad (x)) * 100

  WindowSetPixel (win, x, y + 120, 0xFF0000)

end -- for

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowSetPixel)


WindowSetZOrder

Script function

world.WindowSetZOrder

 Read about scripting

Type

Method

Summary

Sets the Z-Order for a miniwindow

Prototype

long WindowSetZOrder(BSTR WindowName, long Order);

 View list of data type meanings

Description

Sets a Z-Order (drawing order) for the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Order - the order to draw the window. Lower is drawn sooner. Windows with the same Z-Order are drawn in window name order. So for example, the default case of a zero Z-Order results in windows being drawn in name order.

More specifically:

* Windows with a negative Z-order are drawn first (in order, so -2 would be drawn before -1).

* Windows with a zero Z-order (the default) are drawn next, in name order (lower name first)

* Windows with a positive Z-order are drawn last, in Z-order sequence.

* If there are two (or more) windows with the same Z-order number, they are drawn in name order.

Note that being "drawn first" means that a window appears underneath a window which is drawn later.

Return value

eNoSuchWindow - no such miniwindow

eOK - success

 View list of return code meanings

Lua example

WindowSetZOrder (win, 20)

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowSetZOrder)


WindowShow

Script function

world.WindowShow

 Read about scripting

Type

Method

Summary

Shows or hides a miniwindow

Prototype

long WindowShow(BSTR WindowName, BOOL Show);

 View list of data type meanings

Description

This shows or hides the designated window.

WindowName - the name of an existing miniwindow.

Show - true to display the window at its designated place, false to hide it.

Creating and showing windows are separate operations. This is because you may want to maintain something like an inventory list, or quest objectives, but not necessarily have space on the screen for them at a particular moment. By creating the window early on, you can draw to it (offscreen), add or remove items, and generally keep it up-to-date as events occur on the game. However when the player actually wants to see the window s/he may hit a hotkey or type an alias, which simply causes the window to be shown (or hidden).

Calling WindowShow forces a window refresh, so the screen will be updated with the new miniwindow (or absence, as the case may be).

If you have changed the miniwindow, you may not want to call WindowShow (in case they currently want it hidden). In this case you can call Redraw () instead, to cause the main output window to be redrawn, without changing the status of any miniwindows.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

Return value

eNoSuchWindow - no such miniwindow

eOK - success

 View list of return code meanings

Lua example

WindowShow (win, true)  -- show window, refresh screen

WindowShow (win, false) -- hide window, refresh screen

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowShow)


WindowText

Script function

world.WindowText

 Read about scripting

Type

Method

Summary

Draws text into a miniwindow

Prototype

long WindowText(BSTR WindowName, BSTR FontId, BSTR Text, long Left, long Top, long Right, long Bottom, long Colour, BOOL Unicode);

 View list of data type meanings

Description

This draws some text in miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

This function does not do anything special for newlines, carriage-returns, tabs etc.  Probably a box or graphical character will be drawn if you attempt to use them. To handle changing lines you will need to do a second WindowText with the Y (Top) parameter increased. To handle tabbing you would need to increase the X (Left) parameter.

Parameters:

WindowName - the name of an existing miniwindow.

FontId - a font id that you have loaded.

Text - the text to be drawn (maximum of 8192 characters)

Left, Top, Right, Bottom - describes the rectangle to be drawn.

Colour - what colour to draw the text in (RGB)

Unicode - if true, the text is Unicode text in UTF-8 format

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

Return value

If successful, returns the number of pixels the text took horizontally. Thus, by adding that to the "Left" parameter, you can draw some more text to the right of what was just drawn.

If unsuccessful, returns a negative number as follows:

-1 : That window name does not exist

-2 : That font was not loaded

-3 : For Unicode, invalid UTF-8 sequence

Lua example

WindowText (win, "f", "Quest Log",

            5, 10, 0, 0,  -- rectangle

            ColourNameToRGB ("blue"),

            false) -- not Unicode

WindowText (win, "f2", "MUSHclient",

            5, 40, 0, 0,  -- rectangle

            ColourNameToRGB ("saddlebrown"),

            false) -- not Unicode

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowText)


WindowTextWidth

Script function

world.WindowTextWidth

 Read about scripting

Type

Method

Summary

Calculates the width of text in a miniwindow

Prototype

long WindowTextWidth(BSTR WindowName, BSTR FontId, BSTR Text, BOOL Unicode);

 View list of data type meanings

Description

This calculates how many pixels a particular piece of text will take up, which can help in calculating how big a window to create, or where to put other things. Note that WindowText returns the number of pixels when it draws text, so you don't need to call WindowTextWidth simply to work out where to draw the very next item.

WindowName - the name of an existing miniwindow.

FontId - a font id that you have loaded.

Text - the text to be calculated (maximum of 8192 characters)

Unicode - if true, the text is Unicode text in UTF-8 format

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

Return value

If successful, returns the number of pixels the text would take horizontally.

If unsuccessful, returns a negative number as follows:

-1 : That window name does not exist

-2 : That font was not loaded

-3 : For Unicode, invalid UTF-8 sequence

Lua example

width   = WindowTextWidth (win, "f", "Lazy dog yawns")  -- width of text

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowTextWidth)


WindowTransformImage

Script function

world.WindowTransformImage

 Read about scripting

Type

Method

Summary

Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing

Prototype

long WindowTransformImage(BSTR WindowName, BSTR ImageId, float Left, float Top, short Mode, float Mxx, float Mxy, float Myx, float Myy);

 View list of data type meanings

Description

This copies an image to the miniwindow. You specify effectively a "matrix" which is applied to each pixel position, so that the image can be rotated, scaled, reflected, sheared and translated.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, Repaint or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded.

Left, Top - the offset in the destination miniwindow for the image

Mode - the method of drawing the image:

1 - Copy non-transparently to the destination position.

2 - Not used.

3 - Do a transparent copy, where the pixel at the left,top corner (pixel position 0,0) is considered the transparent colour. Any pixels that exactly match that colour are not copied. WARNING - do not choose black or white as the transparent colour as that throws out the calculations. Choose some other colour (eg. purple) - you won't see that colour anyway.

The position of each destination pixel (x' and y') is given by:

  x' = (x * Mxx) + (y * Mxy) + Left

  y' = (x * Myx) + (y * Myy) + Top

Note that if you draw a monchrome image, such as one set up by WindowCreateImage then the pen colour from the most recent drawing operation is used as the foreground colour, and the brush colour for the background colour. Thus you may want to draw a small rectangle (eg. 1 x 1 pixel) with WindowCircleOp to establish those colours first.

For example images and code, see:

http://www.gammon.com.au/forum/?id=10527

Some examples of rotating, scaling, shearing etc. can be found below in the Lua examples.

Note that in some cases you need to also modify the Left and Top parameters or you may not see the result. For example, reflecting an image is likely to reflect it off the side of the bitmap, so you need to add the size of the image back in, to put it back in its original place. The forum posting mentioned above has a discussion about this, and more detailed examples.

Return value

eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage or WindowLoadImageMemory

eBadParameter - drawing mode not in list above or not available due to being run under Windows 95 or earlier

eOK - completed OK

 View list of return code meanings

Lua example

-- IDENTITY COPY (ie. copy without changing)

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 1, 0, 0, 1)

-- TRANSLATE

-- move in X direction

WindowTransformImage (win, imageid, 100, 0, miniwin.image_copy, 1, 0, 0, 1)

-- move in Y direction

WindowTransformImage (win, imageid, 0, 100, miniwin.image_copy, 1, 0, 0, 1)

-- REFLECT ON THE X AXIS

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  -1,  0,  0,  1)

-- REFLECT ON THE Y AXIS

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  1,  0,  0,  -1)

-- REFLECT ON BOTH AXES (ROTATE 180 DEGREES)

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  -1,  0,  0,  -1)

-- ROTATE

-- rotation angle in degrees

local angle = 30

-- angle converted to radians

local radians = math.rad (angle)

-- calculate sine and cosine

local sine   = math.sin (radians)

local cosine = math.cos (radians)

-- rotate counterclockwise

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, cosine, sine,  -sine,  cosine)

-- rotate clockwise

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, cosine, -sine,  sine,  cosine)

-- SHEAR

-- shear vertically right side downwards

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy,  1,  0,  1,  1)

-- shear horizontally, bottom to the right

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  1,  0.5,  0,  1)

-- SCALE

-- make 1.5 times larger

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 1.5, 0, 0, 1.5)

-- reduce to 50%

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 0.5, 0, 0, 0.5)

Lua notes

You can use the following constants for the mode:

miniwin.image_copy = 1

miniwin.image_transparent_copy = 3

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowWrite (Writes the contents of a miniwindow to disk as a graphics file)

(Help topic: function=WindowTransformImage)


WindowWrite

Script function

world.WindowWrite

 Read about scripting

Type

Method

Summary

Writes the contents of a miniwindow to disk as a graphics file

Prototype

long WindowWrite(BSTR WindowName, BSTR FileName);

 View list of data type meanings

Description

The entire contents of the named miniwindow are written to disk as file name FileName. The file name must end in .PNG or .BMP.   Based on the file name, either a BMP or PNG file is written.

The file name is not case-sensitive.

Return value

eNoSuchWindow - no such miniwindow

eNoNameSpecified - no file name specified

eBadParameter - file name too short or does not end in .BMP or .PNG

eCouldNotOpenFile - cannot open file (eg. pathname does not exist, no write permissions)

eLogFileBadWrite - problem writing (eg. disk full)

eOK - success

 View list of return code meanings

Lua example

WindowWrite (win, "window_saved.png");

See Also ...

Topic

 MiniWindows

Functions

 GetDeviceCaps (Gets screen device capabilities)

 SetCursor (Changes the shape of the mouse cursor)

 TextRectangle (Specifies the size of the rectangle in which text is displayed in the output window.)

 WindowAddHotspot (Adds a hotspot  to a miniwindow)

 WindowArc (Draws an arc in a miniwindow)

 WindowBezier (Draws a Bézier curve in a miniwindow)

 WindowBlendImage (Blends an image into a miniwindow, using a specified blending mode)

 WindowCircleOp (Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow)

 WindowCreate (Creates a miniwindow)

 WindowCreateImage (Creates an image in a miniwindow)

 WindowDelete (Deletes a miniwindow)

 WindowDeleteAllHotspots (Deletes all hotspots from a miniwindow)

 WindowDeleteHotspot (Deletes a hotspot from a miniwindow)

 WindowDragHandler (Adds a drag handler to a miniwindow hotspot)

 WindowDrawImage (Draws an image into a miniwindow)

 WindowDrawImageAlpha (Draws an image into a miniwindow respecting the alpha channel)

 WindowFilter (Performs a filtering operation over part of the miniwindow.)

 WindowFont (Loads a font into a miniwindow)

 WindowFontInfo (Returns information about a font)

 WindowFontList (Lists all fonts loaded into a miniwindow)

 WindowGetImageAlpha (Draws the alpha channel of an image into a miniwindow)

 WindowGetPixel (Gets the colour of a single pixel in a miniwindow)

 WindowGradient (Draws a gradient in a rectangle)

 WindowHotspotInfo (Returns information about a hotspot)

 WindowHotspotList (Lists all hotspots installed into a miniwindow)

 WindowHotspotTooltip (Changes the tooltip text for a hotspot in a miniwindow)

 WindowImageFromWindow (Creates an image from another miniwindow)

 WindowImageInfo (Returns information about an image)

 WindowImageList (Lists all images installed into a miniwindow)

 WindowImageOp (Draws an ellipse, rectangle or round rectangle, filled with an image)

 WindowInfo (Returns information about a miniwindow)

 WindowLine (Draws a line in a miniwindow)

 WindowList (Lists all miniwindows)

 WindowLoadImage (Loads an image into a miniwindow from a disk file)

 WindowMenu (Creates a pop-up menu inside a miniwindow)

 WindowMergeImageAlpha (Merges an image into a miniwindow based on an alpha mask)

 WindowMoveHotspot (Moves a hotspot in a miniwindow)

 WindowPolygon (Draws a polygon in a miniwindow)

 WindowPosition (Moves a miniwindow)

 WindowRectOp (Draws a rectangle in a miniwindow)

 WindowResize (Resizes a miniwindow)

 WindowScrollwheelHandler (Adds a scroll-wheel handler to a miniwindow hotspot)

 WindowSetPixel (Sets a single pixel in a miniwindow to the specified colour)

 WindowSetZOrder (Sets the Z-Order for a miniwindow)

 WindowShow (Shows or hides a miniwindow)

 WindowText (Draws text into a miniwindow)

 WindowTextWidth (Calculates the width of text in a miniwindow)

 WindowTransformImage (Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing)

(Help topic: function=WindowWrite)


WorldAddress

Script function

world.WorldAddress

 Read about scripting

Type

Method

Summary

Returns the TCP/IP address of the current world.

Prototype

BSTR WorldAddress();

 View list of data type meanings

Description

Returns the TCP/IP address of the current world.

Return value

TCP/IP address of the current world.

Lua example

Note(WorldAddress())

Jscript example

world.Note(world.WorldAddress());

PerlScript example

$world->Note($world->WorldAddress());

Python example

world.Note(world.WorldAddress)

VBscript example

world.note world.WorldAddress

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldName (Gets the world's name)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=WorldAddress)


WorldName

Script function

world.WorldName

 Read about scripting

Type

Method

Summary

Gets the world's name

Prototype

BSTR WorldName();

 View list of data type meanings

Description

This returns the name of the current world.

Return value

Name of the current world.

Lua example

Note(WorldName())

Jscript example

world.Note(world.WorldName());

PerlScript example

$world->Note($world->WorldName());

Python example

world.Note(world.WorldName)

VBscript example

world.note world.WorldName

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldPort (Returns the port number of the current world.)

(Help topic: function=WorldName)


WorldPort

Script function

world.WorldPort

 Read about scripting

Type

Method

Summary

Returns the port number of the current world.

Prototype

long WorldPort();

 View list of data type meanings

Description

Returns the port number of the current world.

Return value

Port number of the current world.

Lua example

Note(WorldPort())

Jscript example

world.Note(world.WorldPort());

PerlScript example

$world->Note($world->WorldPort());

Python example

world.Note(world.WorldPort)

VBscript example

world.note world.WorldPort

See Also ...

Topic

 Information

Functions

 Debug (Displays debugging information about the world)

 EchoInput (A flag to indicate whether we are echoing command input to the output window)

 GetConnectDuration (Returns the number of seconds this world has been connected.)

 GetEntity (Retrieves the value of an MXP server-defined entity)

 GetHostAddress (Returns a list of IP addresses that correspond to a host name on the Internet)

 GetHostName (Returns the host name that corresponds to an IP address on the Internet)

 GetInfo (Gets information about the current world)

 GetInternalCommandsList (Returns a list of the internal MUSHclient command names)

 GetLineCount (Gets count of lines received)

 GetLineInfo (Gets details about a specified line in the output window)

 GetLinesInBufferCount (Returns the number of lines in the output window)

 GetMainWindowPosition (Returns the position and size of the main MUSHclient window)

 GetNotepadWindowPosition (Returns the position and size of the specified notepad window)

 GetNotes (Gets the world's notes)

 GetQueue (Returns a variant array which is a list of queued commands)

 GetReceivedBytes (Returns the number of bytes received from the world)

 GetRecentLines (Assembles a block of text from recent MUD output)

 GetSelectionEndColumn (Returns the endling column of the selection in the output window)

 GetSelectionEndLine (Returns the last line of the selection in the output window)

 GetSelectionStartColumn (Returns the starting column of the selection in the output window)

 GetSelectionStartLine (Returns the starting line of the selection in the output window)

 GetSentBytes (Returns the number of bytes sent to the world)

 GetStyleInfo (Gets details about a specified style run for a specified line in the output window)

 GetSysColor (Gets the colour of various windows items)

 GetSystemMetrics (Returns selected system information from Windows)

 GetWorldID (Returns the 24-character ID of the current world)

 GetWorldWindowPosition (Returns the position and size of the current world window)

 GetWorldWindowPositionX (Returns the position and size of a specific world window)

 GetXMLEntity (Retrieves the value of a standard entity)

 IsConnected (Tests to see if the world is connected to the MUD server)

 SetChanged (Sets or clears the "document has changed" flag)

 SetEntity (Sets the value of an MXP entity)

 UdpPortList (Returns an array of all the UDP ports in use by this world)

 Version (Gets the MUSHclient version string.)

 WorldAddress (Returns the TCP/IP address of the current world.)

 WorldName (Gets the world's name)

(Help topic: function=WorldPort)


WriteLog

Script function

world.WriteLog

 Read about scripting

Type

Method

Summary

Writes to the log file

Prototype

long WriteLog(BSTR Message);

 View list of data type meanings

Description

This writes a message to the log file.

A "newline" is appended to the line if there is not already one there.

You can also use "LogSend" to send a message to the MUD, and log it, in a single function.

The data in the log file may not appear immediately if you view it in another application. To force the data to disk use the FlushLog function.

Return value

eOK: written OK

eLogFileBadWrite: unable to write to the log file

eLogFileNotOpen: log file was not open

 View list of return code meanings

Lua example

WriteLog("--- Message for the log file ---")

Lua notes

You can supply multiple arguments, which are concatenated together.

Jscript example

world.WriteLog("--- Message for the log file ---");

PerlScript example

$world->WriteLog("--- Message for the log file ---");

Python example

world.WriteLog("--- Message for the log file ---")

VBscript example

world.writelog "--- Message for the log file ---"

See Also ...

Topic

 Logging

Functions

 CloseLog (Closes the log file)

 FlushLog (Flushes the log file to disk)

 IsLogOpen (Tests to see if a log file is open)

 LogInput (The property of whether commands are logged to the log file)

 LogNotes (The property of whether notes are logged to the log file)

 LogOutput (The property of whether MUD output is logged to the log file)

 LogSend (Sends a message to the MUD and logs it)

 OpenLog (Opens a log file.)

(Help topic: function=WriteLog)


assert

Lua function

assert

Summary

Asserts that condition is not nil and not false

Prototype

v = assert (v, message)

Description

Raises an error if value of v is nil or false.

Message is optional, defaults to "assertion failed!".

If no error, returns the value v.

assert (5 == 6, "oh no!") --> error: oh no!

It is very useful that assert returns the value on success, as you can build an assert into the same line that does something that might fail. For example:

assert (loadstring ("print 'hello, world'")) ()

In this case if the loadstring function succeeds it returns a function, that is then executed by the final brackets, otherwise you get an error message.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=assert)


assignment

Assignment lets you "assign" (set) a variable to a value.

eg.

a = 42

b = "hello"

You can do multiple assignments, eg.

a, b = 42, "hello"

That does the same thing as the first example.

Multiple assignments are not generally used on their own (they can be confusing to read), except in collecting the results from a function. Functions can return multiple results, so multiple assignment is a useful way of getting those results. eg.

a, b, c = string.find ("the quick brown fox", "(a+)")

In this example, a will get the start character position of the match, b will get the end position, and c will get the capture.

With multiple assignment, if you (or the function) provides too few values, the extra ones are set to nil, eg.

a, b, c, d = 0, 1

This sets a to 0, b to 1, and c and d are both set to nil.

If you provide too many values, the extra ones are silently discarded, eg.

a = 1, 2, 3, 4, 5, 6

The values 2, 3, 4, 5, 6 are just discarded.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=assignment)


bc.add

Lua function

bc.add

Summary

Addition

Prototype

n = bc.add (a, b)

Description

Returns a + b.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.add)


bc.compare

Lua function

bc.compare

Summary

Comparison

Prototype

n = bc.compare (a, b)

Description

Returns:

•	-1 if a < b

•	 0 if a == b

•	 1 if a > b

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.compare)


bc.digits

Lua function

bc.digits

Summary

Digits after the decimal place

Prototype

old = bc.digits (n)

Description

Do subsequent calculations to n digits after the decimal point.

eg.

bc.digits (20)

a = bc.number (5.5) + 1

print (a)  --> 6.50000000000000000000

Returns the old number of digits, so you could save them, change them, and then restore them.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.digits)


bc.div

Lua function

bc.div

Summary

Division

Prototype

n = bc.div (a, b)

Description

Returns a / b.

If b is zero, returns nil.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.div)


bc.divmod

Lua function

bc.divmod

Summary

Division and remainder

Prototype

n = bc.divmod (a, b)

Description

Returns a / b, and the remainder (a % b).

If b is zero, returns nil.

For example:

print (bc.divmod (7, 3))  -->  2 1

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.divmod)


bc.isneg

Lua function

bc.isneg

Summary

Tests if negative

Prototype

n = bc.isneg (a)

Description

Returns true if a is negative, false otherwise

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.isneg)


bc.iszero

Lua function

bc.iszero

Summary

Tests if zero

Prototype

n = bc.iszero (a)

Description

Returns true if a is zero, false otherwise.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.iszero)


bc.mod

Lua function

bc.mod

Summary

Modulus

Prototype

n = bc.mod (a, b)

Description

Returns a modulus b. That is, the remainder, after dividing a by b.

If b is zero, returns nil.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.mod)


bc.mul

Lua function

bc.mul

Summary

Multiplication

Prototype

n = bc.mul (a, b)

Description

Returns a * b.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.mul)


bc.neg

Lua function

bc.neg

Summary

Negation

Prototype

n = bc.neg (a)

Description

Returns 0 - a

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.neg)


bc.number

Lua function

bc.number

Summary

Create a big number

Prototype

n = bc.number (n)

Description

Create a new big number based on n, where n can be a string if needed, to represent a large number.

eg.

a = bc.number ("1234.45534535345345434")

b = bc.number (5678)

If you are planning to use decimal places, you should call bc.digits first, otherwise the number may not be stored to the number of decimal places you wanted.

eg.

bc.digits (20)

a = bc.number ("1234.45534535345345434")

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.number)


bc.pow

Lua function

bc.pow

Summary

Power

Prototype

n = bc.pow (a, b)

Description

Returns a to the power b. For example:

print (bc.number (2) ^ 100)  --> 1267650600228229401496703205376

print (bc.pow (2, 100))      --> 1267650600228229401496703205376

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.pow)


bc.powmod

Lua function

bc.powmod

Summary

Raise to a power modulus another number

Prototype

n = bc.powmod (b, e, m)

Description

Returns b to the power e modulus m. For example:

print (bc.powmod (2, 9182347891540, 9182347891541))  --> 7569093976632

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.powmod)


bc.sqrt

Lua function

bc.sqrt

Summary

Square root

Prototype

n = bc.sqrt  (a)

Description

Returns the square root of a.

Example:

bc.digits (40)

i = bc.sqrt (2)

print (i) --> 1.4142135623730950488016887242096980785696

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.sqrt)


bc.sub

Lua function

bc.sub

Summary

Subtraction

Prototype

n = bc.sub (a, b)

Description

Returns a - b.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.sub)


bc.tonumber

Lua function

bc.tonumber

Summary

Converts to a number

Prototype

f = bc.tonumber (n)

Description

Converts a big number to a Lua (floating point) number (eg. for use elsewhere in Lua).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.tonumber)


bc.tostring

Lua function

bc.tostring

Summary

Converts to a string

Prototype

s = bc.tostring (n)

Description

Converts a big number to a string (eg. for printing).

eg.

bc.digits (40)

a = bc.sqrt (2)

s = bc.tostring (a)

print (s)  --> 1.4142135623730950488016887242096980785696

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.trunc (Truncate a number)

 bc.version (Version)

(Help topic: lua=bc.tostring)


bc.trunc

Lua function

bc.trunc

Summary

Truncate a number

Prototype

n = bc.trunc (a [, n ] )

Description

Truncates a (gets rid of decimal places). If n is not specified, a is truncated to a whole number. Otherwise n is the number of decimal places wanted.

For example:

bc.digits (10)

print (bc.trunc (1234.567, 1))  -->  1234.5

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.version (Version)

(Help topic: lua=bc.trunc)


bc.version

Lua function

bc.version

Summary

Version

Prototype

bc.version

Description

A string representing the current version of the bc library. eg.

"bc library for Lua 5.1 / Aug 2006 / based on GNU bc-1.06"

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bc.add (Addition)

 bc.compare (Comparison)

 bc.digits (Digits after the decimal place)

 bc.div (Division)

 bc.divmod (Division and remainder)

 bc.isneg (Tests if negative)

 bc.iszero (Tests if zero)

 bc.mod (Modulus)

 bc.mul (Multiplication)

 bc.neg (Negation)

 bc.number (Create a big number)

 bc.pow (Power)

 bc.powmod (Raise to a power modulus another number)

 bc.sqrt (Square root)

 bc.sub (Subtraction)

 bc.tonumber (Converts to a number)

 bc.tostring (Converts to a string)

 bc.trunc (Truncate a number)

(Help topic: lua=bc.version)


bit.ashr

Lua function

bit.ashr

Summary

Shifts a number right, preserving sign

Prototype

n = bit.ashr (num, bits)

Description

This takes two arguments. The first is converted to signed 'long long' (64-bit integer), the second to unsigned 'long long' (64-bit unsigned integer). The first argument is shifted right the number of bits in the second argument.

Use this version for shifting signed numbers right, as it preserves the sign. (The other version, bit.shr, will shift the sign bit into the number part).

eg.

print (bit.ashr (-1024, 6)) --> -16

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.ashr)


bit.band

Lua function

bit.band

Summary

Bitwise 'and'

Prototype

n = bit.band (a, b, ...)

Description

This takes one or more arguments. All are converted to signed 'long long' (64-bit integers). The result is all arguments "and-ed" together bitwise.

eg.

print (bit.band (15, 7, 3)) --> 3

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.band)


bit.bor

Lua function

bit.bor

Summary

Bitwise 'or'

Prototype

n = bit.bor (a, b, ...)

Description

This takes one or more arguments. All are converted to signed 'long long' (64-bit integers).  The result is all arguments "or-ed" together bitwise.

eg.

print (bit.bor (1, 2, 8)) --> 11

Effectively this sets bits (eg. flags).

Note that clearing a bit can be done with bit.clear.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.bor)


bit.clear

Lua function

bit.clear

Summary

Clears one or more bits

Prototype

n = bit.clear (a, b, ...)

Description

This takes one or more arguments. All are converted to signed 'long long' (64-bit integers). The result is the first argument 'and'ed with the ones-complement of the other arguments.

In other words, you can clear any bits in the first argument which are set in subsequent arguments.

eg.

a = bit.clear (0x111, 0x01)  --> 0x110

a = bit.clear (0x111, 0x01, 0x10) --> 0x100

Note that setting a bit can be simply done with bit.bor.

Testing a bit can be done with bit.test.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.clear)


bit.mod

Lua function

bit.mod

Summary

Bitwise 'modulus' (remainder after integer divide)

Prototype

n = bit.mod (a, b)

Description

This takes two arguments. Both are converted to signed 'long long' (64-bit integers). The result is modulus - the remainder after doing an integer divide of the first argument by the second argument.

eg.

print (bit.mod (17, 4))  --> 1

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.mod)


bit.neg

Lua function

bit.neg

Summary

Bitwise 'negate' (ones complement)

Prototype

n = bit.neg (a)

Description

This takes one argument. It is converted to a signed 'long long' (64-bit integer). The result is the ones-complement of the number (zero bits become one, one bits become zero).

eg.

print (bit.neg (1)) --> -2

print (bit.band (14, bit.neg (8)))  --> 6  (clear 8-bit)

Also see bit.clear to achieve the same affect (clearing a bit).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.neg)


bit.shl

Lua function

bit.shl

Summary

Shifts a number left

Prototype

n = bit.shl (num, bits)

Description

This takes two arguments. The first is converted to signed 'long long' (64-bit integer), the second to unsigned 'long long' (64-bit unsigned integer). The first argument is shifted left the number of bits in the second argument.

You can use this for signed or unsigned numbers, as the sign bit will still be preserved.

eg.

print (bit.shl (4, 6)) --> 256

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.shl)


bit.shr

Lua function

bit.shr

Summary

Shifts a number right

Prototype

n = bit.shr (num, bits)

Description

This takes two arguments. Both are converted to unsigned 'long long' (64-bit unsigned integers). The first argument is shifted right the number of bits in the second argument.

eg.

print (bit.shr (1024, 6)) --> 16

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.shr)


bit.test

Lua function

bit.test

Summary

Bitwise 'test'

Prototype

n = bit.test (a, b, ...)

Description

This takes one or more arguments. All are converted to signed 'long long' (64-bit integers).

The second and subsequent arguments are or'ed together. The result is then and'ed with the first argument. The function returns true if the result of the 'and' is the value being 'and'ed with.

Effectively this tests whether or not various bits are set in the first argument.

The result is a boolean (true or false) and thus can be directly used in "if" tests.

eg.

print (bit.test (0x42, 0x02)) --> true

print (bit.test (0x42, 0x40, 0x02)) --> true

print (bit.test (0x02, 0x03)) --> false (0x01 bit not set)

See also bit.band and bit.bor.

Note that setting a bit can be done with bit.bor.

Clearing a bit can be done with bit.clear.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.test)


bit.tonumber

Lua function

bit.tonumber

Summary

Convert a string into a number

Prototype

n = bit.tonumber (s, base)

Description

This takes a string, and converts it into a number. Unlike the standard Lua tonumber function this function will handle up to a 52-bit number (the default Lua number conversion will only go to 32-bit numbers).

eg.

print (bit.tonumber ("A7C5AC471", 16)) -->  45035996273

The base is optional and defaults to 10. The base can be in the range 2 to 36. Fractional numbers are not supported, nor are numbers with exponents (eg. 10.24e15). For such numbers use the standard Lua "tonumber" function.

Because of limitations in the size of a floating point number, the maximum string value that can be converted is a 52 bit number, ie: hex FFFFFFFFFFFFF (decimal 4503599627370495).

Leading whitespace is skipped. After that, there can be an optional + or - sign.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tostring (Convert a number into a string)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.tonumber)


bit.tostring

Lua function

bit.tostring

Summary

Convert a number into a string

Prototype

s = bit.tostring (n, base)

Description

This takes a number, and converts it into a string to the given base, in uppercase. The base is optional and defaults to 10. The base can be in the range 2 to 36. Fractional parts are discarded, as the number is first converted to a 64-bit number internally. Negative numbers are OK, and will be converted with a leading "-" sign.

eg.

print (bit.tostring (45035996273, 16)) -->  A7C5AC471

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.xor (Bitwise 'exclusive or')

(Help topic: lua=bit.tostring)


bit.xor

Lua function

bit.xor

Summary

Bitwise 'exclusive or'

Prototype

n = bit.xor (a, b, ...)

Description

This takes one or more arguments. All are converted to signed 'long long' (64-bit integers). The result is all arguments "exclusive or-ed" together bitwise.

eg.

print (bit.xor (15, 1)) --> 14

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 bit.ashr (Shifts a number right, preserving sign)

 bit.band (Bitwise 'and')

 bit.bor (Bitwise 'or')

 bit.clear (Clears one or more bits)

 bit.mod (Bitwise 'modulus' (remainder after integer divide))

 bit.neg (Bitwise 'negate' (ones complement))

 bit.shl (Shifts a number left)

 bit.shr (Shifts a number right)

 bit.test (Bitwise 'test')

 bit.tonumber (Convert a string into a number)

 bit.tostring (Convert a number into a string)

(Help topic: lua=bit.xor)


break

The break statement is used to terminate a loop (while, repeat or for loop) early.

For example:

while true do

  if mob_in_room () then

    break

  end -- if

end -- while

Also see the return statement which is used to leave the current function (not just the current loop).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=break)


collectgarbage

Lua function

collectgarbage

Summary

Collects garbage

Prototype

collectgarbage (opt, arg)

Description

Note that this has changed considerably since Lua 5.0.

•	"stop": stops the garbage collector.

•	"restart": restarts the garbage collector.

•	"collect": performs a full garbage-collection cycle (this is the default if no option supplied)

•	"count": returns the total memory in use by Lua (in Kbytes).

•	"step": performs a garbage-collection step. The step "size" is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle.

•	"setpause": sets arg/100 as the new value for the pause of the collector (see below).

•	"setstepmul": sets arg/100 as the new value for the step multiplier of the collector (see below).

Lua implements an incremental mark-and-sweep collector. It uses two numbers to control its garbage-collection cycles: the garbage-collector pause and the garbage-collector step multiplier.

The garbage-collector pause controls how long the collector waits before starting a new cycle. Larger values make the collector less aggressive. Values smaller than 1 mean the collector will not wait to start a new cycle. A value of 2 means that the collector waits for the total memory in use to double before starting a new cycle.

The step multiplier controls the relative speed of the collector relative to memory allocation. Larger values make the collector more aggressive but also increase the size of each incremental step. Values smaller than 1 make the collector too slow and may result in the collector never finishing a cycle. The default, 2, means that the collector runs at "twice" the speed of memory allocation.

Both "setpause" and "setstepmul" get percentage points as arguments (so an argument of 100 means a real value of 1). Both default to 200 when Lua starts up (and since they are divided by 100, effectively the default is 2 as described above).

collectgarbage ("collect") --> forces garbage collection

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=collectgarbage)


comments

A single-line comments starts with "--" and ends at the end of the line, eg.

a = 42 -- initial value of 'a'

You can also use "block" comments by following the hyphens by brackets like this:

--[[

  Written by Nick Gammon.

  Date: 3rd June 2011

]]

To allow for nesting block comments you can add in one or more "=" symbols like this:

--[=[

  Written by Nick Gammon.

  Date: 3rd June 2011

  --[===[

    Nested comment.

  ]===]

  Not nested.

]=]

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=comments)


context:aggregate_count

Lua function

context:aggregate_count

Summary

Returns the number of calls to the aggregate step function.

Prototype

context:aggregate_count()

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:aggregate_count)


context:get_aggregate_data

Lua function

context:get_aggregate_data

Summary

Returns the user-definable data field for callback functions.

Prototype

context:get_aggregate_data()

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:get_aggregate_data)


context:result

Lua function

context:result

Summary

This function sets the result of a callback function to res.

Prototype

context:result(res)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

The type of the result depends on the type of res and is either a number or a string or nil. All other values will raise an error message.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result)


context:result_blob

Lua function

context:result_blob

Summary

This function sets the result of a callback function to the binary string in blob.

Prototype

context:result_blob(blob)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_blob)


context:result_error

Lua function

context:result_error

Summary

This function sets the result of a callback function to the error value in err.

Prototype

context:result_error(err)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_error)


context:result_int

Lua function

context:result_int

Summary

This function sets the result of a callback function to the  integer value in number

Prototype

context:result_int(number)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_int)


context:result_null

Lua function

context:result_null

Summary

This function sets the result of a callback function to nil.

Prototype

context:result_null()

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_null)


context:result_number

Lua function

context:result_number

Summary

This function sets the result of a callback function to the value number.

Prototype

context:result_number(number) or context:result_double(number)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_number)


context:result_text

Lua function

context:result_text

Summary

This function sets the result of a callback function to the string in str.

Prototype

context:result_text(str)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

It returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:result_text)


context:set_aggregate_data

Lua function

context:set_aggregate_data

Summary

Set the user-definable data field for callback functions to udata.

Prototype

context:set_aggregate_data(udata)

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:set_aggregate_data)


context:user_data

Lua function

context:user_data

Summary

Returns the userdata parameter given in the call to install the callback function.

Prototype

context:user_data()

Description

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

Returns the userdata parameter given in the call to install the callback function (see db:create_aggregate() and db:create_function() for details).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=context:user_data)


coroutine.create

Lua function

coroutine.create

Summary

Creates a new coroutine thread

Prototype

thread = coroutine.create (f)

Description

Creates a thread consisting of the body f.

thread = coroutine.create (f)

Then you can resume it with coroutine.resume.

For example:

function f (a, b, c)

  print (a, b, c)

end -- f

thread = coroutine.create (f)  -- thread will run function f

assert (coroutine.resume (thread, 1, 2, 3))  -- start thread, passing arguments: 1, 2, 3

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.resume (Start or resume a thread)

 coroutine.running (Returns the running coroutine)

 coroutine.status (Returns the status of a thread)

 coroutine.wrap (Creates a thread and returns a function to resume it)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: lua=coroutine.create)


coroutine.resume

Lua function

coroutine.resume

Summary

Start or resume a thread

Prototype

ok, args = coroutine.resume (thread, v1, v2, ...)

Description

Start or resume a thread created by coroutine.create. Any values supplied after the thread are returned as results from the coroutine.yield inside the thread. If this is the first call for this thread, the values are supplied to the function itself.

On success, returns true, followed by arguments to the coroutine.yield inside the function (if called), or the return  value of the function itself.

On failure, returns false followed by an error message.

assert (coroutine.resume (thread, 45, 67))

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.running (Returns the running coroutine)

 coroutine.status (Returns the status of a thread)

 coroutine.wrap (Creates a thread and returns a function to resume it)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: lua=coroutine.resume)


coroutine.running

Lua function

coroutine.running

Summary

Returns the running coroutine

Prototype

thread = coroutine.running ()

Description

Returns the running coroutine, or no value when called by the main thread.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.resume (Start or resume a thread)

 coroutine.status (Returns the status of a thread)

 coroutine.wrap (Creates a thread and returns a function to resume it)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: lua=coroutine.running)


coroutine.status

Lua function

coroutine.status

Summary

Returns the status of a thread

Prototype

s = coroutine.status (thread)

Description

Returns a string indicating the status of the thread. Raises an error if the argument is not a thread.

If it is, the values returned can be:

•	running

•	normal

•	suspended

•	dead

A thread is "running" if coroutine.status is called from within the thread itself.

A thread is "normal" if the coroutine is active, but has resumed another coroutine.

It is "suspended" after being created but before it is resumed, and after yielding.

It is "dead" after it has returned from the entire function.

print (coroutine.status (thread)) --> suspended

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.resume (Start or resume a thread)

 coroutine.running (Returns the running coroutine)

 coroutine.wrap (Creates a thread and returns a function to resume it)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: lua=coroutine.status)


coroutine.wrap

Lua function

coroutine.wrap

Summary

Creates a thread and returns a function to resume it

Prototype

f = coroutine.wrap (f)

Description

Creates a thread with body f, and then returns a function that can be used to resume the thread. This is a slightly simpler interface than the coroutine.create / coroutine.resume sequence, however it makes error management harder.

function f (s)

  print ("Entering f with value", s)

  v = coroutine.yield ()

  print ("After yield, v is", v)

  return 22

end -- f

resumer = coroutine.wrap (f)

resumer (88)  -- start thread

resumer (99)  -- resume after yield

 -->

Entering f with value 88

After yield, v is 99

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.resume (Start or resume a thread)

 coroutine.running (Returns the running coroutine)

 coroutine.status (Returns the status of a thread)

 coroutine.yield (Yields execution of thread back to the caller)

(Help topic: lua=coroutine.wrap)


coroutine.yield

Lua function

coroutine.yield

Summary

Yields execution of thread back to the caller

Prototype

args = coroutine.yield (v1, v2, ...)

Description

Yields execution back to the caller, effectively creating co-operative multi-tasking. Values supplied to yield are returned to coroutine.resume.

The coroutine cannot be running a C function, a metamethod, or an iterator.

Returns any arguments passed to the thread from coroutine.resume.

function f (s)

  print ("Entering f with value", s)

  v = coroutine.yield ("goat")

  print ("After yield, v is", v)

  return 22

end -- f

thread = coroutine.create (f)

ok, result = coroutine.resume (thread, 42) -- start it up

assert (ok, result) -- check ok

print (result) -- see what the yield returned

ok, result = coroutine.resume (thread, 55) -- resume it

assert (ok, result) -- check ok

print (result) -- see what the function returned

 -->

Entering f with value 42

goat

After yield, v is 55

22

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 coroutine.create (Creates a new coroutine thread)

 coroutine.resume (Start or resume a thread)

 coroutine.running (Returns the running coroutine)

 coroutine.status (Returns the status of a thread)

 coroutine.wrap (Creates a thread and returns a function to resume it)

(Help topic: lua=coroutine.yield)


data types

There are eight basic types in Lua:

•	nil

•	boolean

•	number

•	string

•	table

•	function

•	userdata

•	thread

Note that values are typed, not variables. That is, a variable "foo" can contain any type of data, and that the type can change from moment to moment.

You can find the type of a value by using the "type" function, for example:

print (type ("nick"))  --> string

The word returned by the "type" function will be one of the words in the list above.

nil

The value nil basically represents "no value". Global variables have the value nil by default, until something is assigned to them.

boolean

Boolean types only have two values, which are true and false.

Boolean types are usually used where you simply want to record if something is true or not.

However when doing condition tests (eg. an "if" statement) only two values are considered false:

•	nil

•	false

Every other value (including zero, and an empty string) are considered true.

number

The number type holds numbers (internally as the "double" floating point type). There is no integer type, as the double type can hold integers without rounding errors up to 100,000,000,000,000. *

In the case of MUSHclient, which is compiled with Microsoft Visual C++, the double type is documented to be in the range: 1.7E +/- 308 (15 digits)

Numeric constants can be written with optional signs, decimal points and exponents like this:

42   -42.3   4.56e7   7.89e-10  0.3e12   22E+42

Numeric constants can also be written in hexadecimal like this:

0xA   0X0D   0x123456

* See: http://en.wikipedia.org/wiki/Double_precision_floating-point_format

The mantissa of "double" numbers is 53 bits, giving it the ability to store a precision of almost 16 digits. (53 * math.log10(2) == 15.95 digits).

string

Strings are any sequence of characters, including none. Strings are "8-bit clean" which means you can store any character in them including 0x00.

Literal strings are delimited by single or double quotes. The same quote that starts the string ends it, allowing you to use the other quote inside the string, eg.

a = "Nick's cat"

b = 'Nick says "hello" to you'

Copying strings is fast as there is only ever one copy of the same string. Strings cannot be modified "in place". To change a string you always make a new copy.

If you attempt to do arithmetic on a string Lua will try to convert it to a number for you. For example:

print("42" + 1)       --> 43

print("1e5" * "1e2")  --> 10000000

However strings always compare unequal to numbers:

print ("42" == 42)  --> false

See the entry for "string literals" for more details about strings.

function

Functions are "code that can be executed". They can be either written in Lua (by you) or C (the internal libraries).

They are "first-class" values, that is they can be stored in variables, passed as arguments to other functions, and can be returned as the return value of another function. For example:

f = print    --  Assign the print function to the variable f

f ("hello")  --> hello

See the entry for "function" for more details about functions.

table

Tables implement associative arrays. That is, arrays of key/value pairs.

The keys and values can be any type, except nil.

The only way to create a table is by using a "table constructor" like this:

my_table = { }

The table constructor can also add initial key/value pairs to the table, eg.

foods = {

   fish  = 10,

   chips = 11,

   cake  = 12

   }

In this example "fish" is a key, and the number 10 is the value associated with that key.

See the entry for "tables" for more details about tables.

userdata

The userdata type lets Lua store "C" data into a Lua variable. This is mainly used by libraries, for example to hold information about open files, regular expressions and so on.

thread

Threads are used for co-routines, which are independent units of execution which can yield execution to the caller and resume later.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=data types)


db:busy_handler

Lua function

db:busy_handler

Summary

Sets or removes a busy handler for a database

Prototype

db:busy_handler([func[,udata]])

Description

Sets or removes a busy handler for a database. func is either a Lua function that implements the busy handler or nil to remove a previously set handler. This function returns nothing.

The handler function is called with two parameters: udata and the number of (re-)tries for a pending transaction. It should return nil, false or 0 if the transaction is to be aborted. All other values will result in another attempt to perform the transaction. (See the SQLite documentation for important hints about writing busy handlers.)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:busy_handler)


db:busy_timeout

Lua function

db:busy_timeout

Summary

Sets a busy handler

Prototype

db:busy_timeout(t)

Description

Sets a busy handler that waits for t milliseconds if a transaction cannot proceed. Calling this function will remove any busy handler set by db:busy_handler(); calling it with an argument less than or equal to 0 will turn off all busy handlers.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:busy_timeout)


db:changes

Lua function

db:changes

Summary

Returns number of changes by the most recent SQL statement

Prototype

db:changes()

Description

This function returns the number of database rows that were changed (or inserted or deleted) by the most recent SQL statement. Only changes that are directly specified by INSERT, UPDATE, or DELETE statements are counted. Auxiliary changes caused by triggers are not counted. Use db:total_changes() to find the total number of changes.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:changes)


db:close

Lua function

db:close

Summary

Closes a database

Prototype

db:close()

Description

Closes a database. All SQL statements prepared using db:prepare() should have been finalized before this function is called. The function returns sqlite3.OK on success or else a numerical error code (see the list of Numerical error and result codes).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:close)


db:close_vm

Lua function

db:close_vm

Summary

Finalizes all statements that have not been explicitly finalized

Prototype

db:close_vm(temponly)

Description

Finalizes all statements that have not been explicitly finalized. If temponly is true, only internal, temporary statements are finalized. This function returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:close_vm)


db:create_aggregate

Lua function

db:create_aggregate

Summary

Creates an aggregate callback function

Prototype

db:create_aggregate(name,nargs,step,final)

Description

This function creates an aggregate callback function. Aggregates perform an operation over all rows in a query. name is a string with the name of the aggregate function as given in an SQL statement; nargs is the number of arguments this call will provide. step is the actual Lua function that gets called once for every row; it should accept a function context (see below for callback contexts) plus the same number of parameters as given in nargs. final is a function that is called once after all rows have been processed; it receives one argument, the function context.

The function context can be used inside the two callback functions to communicate with SQLite3. Here is a simple example:

        db:exec[=[

          CREATE TABLE numbers(num1,num2);

          INSERT INTO numbers VALUES(1,11);

          INSERT INTO numbers VALUES(2,22);

          INSERT INTO numbers VALUES(3,33);

        ]=]

        local num_sum=0

        local function oneRow(context,num)  -- add one column in all rows

          num_sum=num_sum+num

        end

        local function afterLast(context)   -- return sum after last row has been processed

          context:result_number(num_sum)

          num_sum=0

        end

        db:create_aggregate("do_the_sums",1,oneRow,afterLast)

        for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end

        for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end

This prints:

        Sum of col 1:   6

        Sum of col 2:   66

CALLBACK CONTEXTS

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

The various context functions are:

context:aggregate_count

context:get_aggregate_data

context:result

context:result_blob

context:result_error

context:result_int

context:result_null

context:result_number

context:result_text

context:set_aggregate_data

context:user_data

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:create_aggregate)


db:create_collation

Lua function

db:create_collation

Summary

Creates a collation callback

Prototype

db:create_collation(name,func)

Description

This creates a collation callback. A collation callback is used to establish a collation order, mostly for string comparisons and sorting purposes. name is a string with the name of the collation to be created; func is a function that accepts two string arguments, compares them and returns 0 if both strings are identical, -1 if the first argument is lower in the collation order than the second and 1 if the first argument is higher in the collation order than the second. A simple example:

        local function collate(s1,s2)

          s1=s1:lower()

          s2=s2:lower()

          if s1==s2 then return 0

          elseif s1<s2 then return -1

          else return 1 end

        end

        db:exec[=[

          CREATE TABLE test(id INTEGER PRIMARY KEY,content COLLATE CINSENS);

          INSERT INTO test VALUES(NULL,'hello world');

          INSERT INTO test VALUES(NULL,'Buenos dias');

          INSERT INTO test VALUES(NULL,'HELLO WORLD');

        ]=]

        db:create_collation('CINSENS',collate)

        for row in db:nrows('SELECT * FROM test') do print(row.id,row.content) end

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:create_collation)


db:create_function

Lua function

db:create_function

Summary

Creates a callback function

Prototype

db:create_function(name,nargs,func)

Description

This function creates a callback function. Callback function are called by SQLite3 once for every row in a query. name is a string with the name of the callback function as given in an SQL statement; nargs is the number of arguments this call will provide. func is the actual Lua function that gets called once for every row; it should accept a function context (see below for callback contexts) plus the same number of parameters as given in nargs. Here is an example:

        db:exec'CREATE TABLE test(col1,col2,col3)'

        db:exec'INSERT INTO test VALUES(1,2,4)'

        db:exec'INSERT INTO test VALUES(2,4,9)'

        db:exec'INSERT INTO test VALUES(3,6,16)'

        db:create_function('sum_cols',3,function(ctx,a,b,c)

          ctx:result_number(a+b+c)

        end))

        for col1,col2,col3,sum in db:urows('SELECT *,sum_cols(col1,col2,col3) FROM test') do

          print (string.format ('%2i+%2i+%2i=%2i\n',col1,col2,col3,sum))

        end

CALLBACK CONTEXTS

A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.

The various context functions are:

context:aggregate_count

context:get_aggregate_data

context:result

context:result_blob

context:result_error

context:result_int

context:result_null

context:result_number

context:result_text

context:set_aggregate_data

context:user_data

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:create_function)


db:errcode

Lua function

db:errcode

Summary

Returns the most recent result code

Prototype

db:errcode()

Description

Returns the numerical result code (or extended result code) for the most recent failed call associated with database db. See Numerical error and result codes for details.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:errcode)


db:errmsg

Lua function

db:errmsg

Summary

Returns the most recent error message

Prototype

db:errmsg()

Description

Returns a string that contains an error message for the most recent failed call associated with database db.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:errmsg)


db:exec

Lua function

db:exec

Summary

Executes SQL statements

Prototype

db:exec(sql[,func[,udata]])

Description

Compiles and executes the SQL statement(s) given in string sql. The statements are simply executed one after the other and not stored. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes).

If one or more of the SQL statements are queries, then the callback function specified in func is invoked once for each row of the query result (if func is nil, no callback is invoked). The callback receives four arguments: udata (the third parameter of the db:exec() call), the number of columns in the row, a table with the column values and another table with the column names. The callback function should return 0. If the callback returns a non-zero value then the query is aborted, all subsequent SQL statements are skipped and db:exec() returns sqlite3.ABORT. Here is a simple example:

        sql=[=[

          CREATE TABLE numbers(num1,num2,str);

          INSERT INTO numbers VALUES(1,11,"ABC");

          INSERT INTO numbers VALUES(2,22,"DEF");

          INSERT INTO numbers VALUES(3,33,"UVW");

          INSERT INTO numbers VALUES(4,44,"XYZ");

          SELECT * FROM numbers;

        ]=]

        function showrow(udata,cols,values,names)

          assert(udata=='test_udata')

          print('exec:')

          for i=1,cols do print('',names[i],values[i]) end

          return 0

        end

        db:exec(sql,showrow,'test_udata')

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:exec)


db:interrupt

Lua function

db:interrupt

Summary

Interrupts any pending operation

Prototype

db:interrupt()

Description

This function causes any pending database operation to abort and return at the next opportunity. This function returns nothing.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:interrupt)


db:isopen

Lua function

db:isopen

Summary

Tests if the database is open

Prototype

db:isopen()

Description

Returns true if database db is open, false otherwise.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:isopen)


db:last_insert_rowid

Lua function

db:last_insert_rowid

Summary

Returns the key of the most recent insert into the database

Prototype

db:last_insert_rowid()

Description

This function returns the rowid of the most recent INSERT into the database. If no inserts have ever occurred, 0 is returned. (Each row in an SQLite table has a unique 64-bit signed integer key called the 'rowid'. This id is always available as an undeclared column named ROWID, OID, or _ROWID_. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.)

If an INSERT occurs within a trigger, then the rowid of the inserted row is returned as long as the trigger is running. Once the trigger terminates, the value returned reverts to the last value inserted before the trigger fired.

This returns a Lua number if possible, otherwise if the key is too large to be stored in a number it returns a string.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:last_insert_rowid)


db:nrows

Lua function

db:nrows

Summary

Creates an iterator that returns a table of rows from a SELECT - keyed by name

Prototype

db:nrows(sql)

Description

Creates an iterator that returns the successive rows selected by the SQL statement given in string sql. Each call to the iterator returns a table in which the named fields correspond to the columns in the database. Here is an example:

        db:exec[=[

          CREATE TABLE numbers(num1,num2);

          INSERT INTO numbers VALUES(1,11);

          INSERT INTO numbers VALUES(2,22);

          INSERT INTO numbers VALUES(3,33);

        ]=]

        for a in db:nrows('SELECT * FROM numbers') do table.print(a) end

This script prints:

        num2: 11

        num1: 1

        num2: 22

        num1: 2

        num2: 33

        num1: 3

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:nrows)


db:prepare

Lua function

db:prepare

Summary

Compiles an SQL statement

Prototype

db:prepare(sql)

Description

This function compiles the SQL statement in string sql into an internal representation and returns this as userdata. The returned object should be used for all further method calls in connection with this specific SQL statement.

CALLBACK CONTEXTS

A callback context is available as a parameter inside the callback functions db:create_aggregate(),  db:create_function() and db:prepare(). It can be used to get further information about the state of a query.

The various context functions are:

context:aggregate_count

context:get_aggregate_data

context:result

context:result_blob

context:result_error

context:result_int

context:result_null

context:result_number

context:result_text

context:set_aggregate_data

context:user_data

Example

require "tprint"

-- make in-memory database

db = sqlite3.open_memory()

-- make a table for testing

db:exec  [[

          CREATE TABLE mobs (name, class, hp);

          INSERT INTO mobs VALUES("Naga", "mage", 666);

          INSERT INTO mobs VALUES("Wolf", "beast", 42);

          INSERT INTO mobs VALUES("Guard", "warrior", 100);

       ]]

-- prepare a SELECT statement

local stmt = db:prepare ("SELECT * FROM mobs")

-- loop until we get everything

while true do

  local result = stmt:step ()

  -- exit loop if done

  if result == sqlite3.DONE then

    break

  end -- if done

  -- should have ROW result

  assert (result == sqlite3.ROW, "Row not found")

  -- get all values into a table

  local row = stmt:get_named_values ()

  -- display them

  print (string.rep ("-", 20))

  tprint (row)

end -- while

-- done with this statement

stmt:finalize ()

-- finished with database

db:close ()

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:prepare)


db:progress_handler

Lua function

db:progress_handler

Summary

Installs a progress callback function

Prototype

db:progress_handler(n,func,udata)

Description

This function installs a callback function func that is invoked periodically during long-running calls to db:exec() or stmt:step(). The progress callback is invoked once for every n internal operations, where n is the first argument to this function. udata is passed to the progress callback function each time it is invoked. If a call to db:exec() or stmt:step() results in fewer than n operations being executed, then the progress callback is never invoked. Only a single progress callback function may be registered for each opened database and a call to this function will overwrite any previously set callback function. To remove the progress callback altogether, pass nil as the second argument.

If the progress callback returns a result other than 0, then the current query is immediately terminated, any database changes are rolled back and the containing db:exec() or stmt:step() call returns sqlite3.INTERRUPT. This feature can be used to cancel long-running queries.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:progress_handler)


db:rows

Lua function

db:rows

Summary

Creates an iterator that returns a table of rows from a SELECT - numerically keyed

Prototype

db:rows(sql)

Description

Creates an iterator that returns the successive rows selected by the SQL statement given in string sql. Each call to the iterator returns a table in which the numerical indices 1 to n correspond to the selected columns 1 to n in the database. Here is an example:

        db:exec[=[

          CREATE TABLE numbers(num1,num2);

          INSERT INTO numbers VALUES(1,11);

          INSERT INTO numbers VALUES(2,22);

          INSERT INTO numbers VALUES(3,33);

        ]=]

        for a in db:rows('SELECT * FROM numbers') do table.print(a) end

This script prints:

        1: 1

        2: 11

        1: 2

        2: 22

        1: 3

        2: 33

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:rows)


db:total_changes

Lua function

db:total_changes

Summary

Returns total number of changes

Prototype

db:total_changes()

Description

This function returns the number of database rows that have been modified by INSERT, UPDATE or DELETE statements since the database was opened. This includes UPDATE, INSERT and DELETE statements executed as part of trigger programs. All changes are counted as soon as the statement that produces them is completed by calling either stmt:reset() or stmt:finalize().

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:total_changes)


db:trace

Lua function

db:trace

Summary

Installs debug trace callback

Prototype

db:trace(func,udata)

Description

This function installs a trace callback handler. func is a Lua function that is called by SQLite3 just before the evaluation of an SQL statement. This callback receives two arguments: the first is the udata argument used when the callback was installed; the second is a string with the SQL statement about to be executed.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:trace)


db:urows

Lua function

db:urows

Summary

Creates an iterator that returns the rows from a SELECT

Prototype

db:urows(sql)

Description

Creates an iterator that returns the successive rows selected by the SQL statement given in string sql. Each call to the iterator returns the values that correspond to the columns in the currently selected row.

The difference between this and db:rows is that this function does not return a table, it returns the individual values as part of the function return value.

 Here is an example:

        db:exec[=[

          CREATE TABLE numbers(num1,num2);

          INSERT INTO numbers VALUES(1,11);

          INSERT INTO numbers VALUES(2,22);

          INSERT INTO numbers VALUES(3,33);

        ]=]

        for num1,num2 in db:urows('SELECT * FROM numbers') do print(num1,num2) end

This script prints:

        1       11

        2       22

        3       33

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=db:urows)


debug.debug

Lua function

debug.debug

Summary

Enters interactive debugging

Prototype

debug.debug ()

Description

Enters interactive debugging. MUSHclient has an interactive debug dialog box which lets you inspect local variables and upvalues, do a traceback, enter debugging commands, and then continue or abort the script.

debug.debug () -- enter debugger

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.debug)


debug.getfenv

Lua function

debug.getfenv

Summary

Returns the environment of an object

Prototype

t = debug.getfenv (obj)

Description

Returns the environment of object obj. This differs a bit from the base function getfenv, which takes a function or a level number, and converts the level number into a function. The debug version simply returns the environment of the argument, which is only meaningful for objects of type function, userdata or thread.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getfenv)


debug.gethook

Lua function

debug.gethook

Summary

Returns the current hook settings

Prototype

f, mask, count = debug.gethook (thread)

Description

Returns the current hook settings as three values:

•	Hook function

•	Mask

•	Count

See debug.sethook for more details.

The thread argument is optional and defaults to the current thread.

f, mask, count = debug.gethook ()

print (f) --> nil

print (mask) --> ""

print (count) --> 0

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.gethook)


debug.getinfo

Lua function

debug.getinfo

Summary

Returns a table with information about a function

Prototype

t = debug.getinfo (thread, f, what)

Description

Returns a table with information about a function. The optional field "what" is a string indicating which values to return (can be more than one). If omitted, all is returned.

The thread argument is optional and defaults to the current thread.

What fields can be one or more of the following concatenated together:

•	f - returns "func" field

•	l - returns "currentline" field

•	L - returns a table whose indices are the numbers of the lines that are valid on the function. (A valid line is a line with some associated code, that is, a line where you can put a break point. Non-valid lines include empty lines and comments.)

•	n - returns "name" and "namewhat" fields

•	S - returns "source", "short_src", "linedefined" and "what" fields

•	u - returns "nups" field

The function name can be an integer representing the stack level, where 0 is debug.getinfo itself, 1 is the function that called debug.getinfo, 2 is the function that called that, and so on. Returns nil if the function number is larger than the number of functions on the stack.

Field meanings of the returned table are:

•	source - where the function was defined. If in a file, it is the file name prefixed by "@".

If the function was defined in a string (through loadstring) then "source" is this string.

If the function was defined interactively (through the lua.exe program) then source will be "stdin".

If the function was defined in a C program, then source will be "[C]".

•	short_src - a shorter version of "source" (up to 60 characters), useful for error messages

•	linedefined - the first line number, in the source, where this function was defined (for Lua functions).

•	lastlinedefined - the last line number, in the source, where this function was defined (for Lua functions).

•	what - what this function is. Can be "Lua" for a regular Lua function, "C" if it is a C function, or "main" if it is part of the main Lua chunk (ie. outside any function).

•	name - an attempt to find the name of the function - may be nil.

Since functions can have many names (by assigning a function to many variables) or no name, the name cannot always be determined.

Lua tries to find the name of the function by inspecting the call stack to find how the function was called. This can only work if debug.getinfo was called with a stack level number, not a function itself.

•	namewhat - what the "name" field means. It can be "global", "local", "method", "field", or the empty string (""). The empty string means Lua did not find the name, and thus the name field will not be present.

•	nups - the number of upvalues that this function has.

•	activelines - a table of the active lines of the function, that is ones which have code on them, as opposed to blank lines or comments. Each entry in table contains the line number as a key, and true as the value.

•	currentline - the line that is currently active (only applies to active functions, that is if the call to debug.getinfo is for a stack level).

•	func - the function that is active at that stack level (if called with a stack level).

t = debug.getinfo (table.sort)

table.foreach (t, print)

 -->

source =[C]

what C

func function: 02061360

short_src [C]

currentline -1

namewhat

linedefined -1

nups 0

-- another example, this time a user-defined function --

function f (a, b, c) print "hi" end

t = debug.getinfo (f, "flnSu")  --> 'what' options explicitly mentioned

table.foreach (t, print)

 -->

source  =stdin

what    Lua

func    function: 0x8079a40

name    f

nups    0

currentline     -1

namewhat        global

linedefined     1

short_src       stdin

-- this example prints the name of the currently-running function --

function myfunc () print (debug.getinfo (1, "n").name) end

myfunc ()  --> myfunc

-- this example shows the active lines:

function f (a, b, c)

print "hi"

a = b + c

end

t = debug.getinfo (f, "L")

table.foreach (t.activelines, print)

 -->

2	true

3	true

4	true

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getinfo)


debug.getlocal

Lua function

debug.getlocal

Summary

Returns name and value of a local variable

Prototype

name, val = debug.getlocal (level, local)

Description

Returns the name and value of the local variable with the index 'local' of the function at 'level' on the stack.

See also debug.setlocal .

function f (a, b)

local c = 11

local i = 1

repeat

  name, val = debug.getlocal (1, i)

  if name then

    print ("index", i, name, "=", val)

    i = i + 1

  end -- if

until not name

end -- function f

f (22, 33)

 -->

index 1 a = 22

index 2 b = 33

index 3 c = 11

index 4 i = 4

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getlocal)


debug.getmetatable

Lua function

debug.getmetatable

Summary

Returns the metatable of the given object

Prototype

t = debug.getmetatable (obj)

Description

Returns the metatable of the given object or nil if it does not have a metatable.

Bypasses the check for the "__metatable" entry.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getmetatable)


debug.getregistry

Lua function

debug.getregistry

Summary

Returns the registry table

Prototype

t = debug.getregistry ()

Description

Returns the registry table. This is a special table used by C functions to store information it wants to keep isolated from Lua functions.

table.foreach (debug.getregistry (), print)

  -->

FILE* table: 01B43F50

_LOADLIB table: 01B42BC0

mushclient.world table: 01B4BBC0

_LOADED table: 01B418C0

mushclient.document userdata: 017A8C58

pcre_regex_handle table: 01B4E830

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getregistry)


debug.getupvalue

Lua function

debug.getupvalue

Summary

Returns the name and value of an upvalue

Prototype

name, value = debug.getupvalue (level, upvalue)

Description

Similar to debug.getlocal, returns the names and values of the upvalues for the nominated function. See also debug.setupvalue.

function newCounter ()

  local n = 0

  return function ()  -- anonymous function

    n = n + 1

    return n

    end -- function

end -- newCounter

c = newCounter ()

c ()  -- count a couple of times

c ()

-- show upvalues in c

local i = 1

repeat

  name, val = debug.getupvalue (c, i)

  if name then

    print ("index", i, name, "=", val)

    i = i + 1

  end -- if

until not name

 -->

 index 1 n = 2

In this example the function c is a closure (with associated upvalue "n").

NOTE: Lua does not let you see or change upvalues for C functions (eg. string.gfind).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.getupvalue)


debug.setfenv

Lua function

debug.setfenv

Summary

Sets the environment of an object

Prototype

obj = debug.setfenv (object, table)

Description

Sets the environment of the given object to the given table. Returns object. Similarly to debug.getfenv, this function takes a raw object (unlike the base setfenv function which can also take a function level).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.setfenv)


debug.sethook

Lua function

debug.sethook

Summary

Sets a debug hook function

Prototype

debug.sethook (thread, f, mask, count)

Description

Sets the function f as a hook to be called when the "mask" condition is satisfied.

If count is non-zero, it is called after every "count" instructions.

The thread argument is optional and defaults to the current thread.

If called without arguments, turns off the hook.

Mask can be one or more of:

•	c - called every time Lua calls a function

•	r - called every time Lua returns from a function

•	l - called every time Lua enters a new line of code

The mask can be the empty string if you simply want to hook after "count" instructions.

The function f is called with its first parameter being a string, which can be one of:

•	call

•	return

•	tail return

•	line

•	count

In the case of "line" events it gets a second parameter, being the new line number.

Inside the hook you can use debug.getinfo with level 2 to find information about the running function. (Level 0 is getinfo, and level 1 is the hook function). In the case of "tail return" however debug.getinfo will not return valid information.

Here is an example of setting a hook to stop a runaway function from executing for too long:

function test ()

  a = 0

  for i = 0, 1000 do

    a = a + i

  end -- for

end -- test

function hook (why)

  error ("hook reached: " .. why)

end -- hook

debug.sethook (hook, "", 100)

test () --> error:  hook reached: count

In this case, the hook stopped execution after 100 instructions.

This second example uses a "call" hook to display when each new function is entered:

function f ()

  function g ()

  end -- g

 g ()

 g ()

end -- f

function hook (why)

  print ("hook reached: ", why)

  print ("function =", debug.getinfo (2, "n").name)

end -- hook

debug.sethook (hook, "c", 0)

f ()

 -->

hook reached:  call

function = f

hook reached:  call

function = g

hook reached:  call

function = g

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.sethook)


debug.setlocal

Lua function

debug.setlocal

Summary

Sets the value of the local variable

Prototype

debug.setlocal (level, local, value)

Description

Sets the value of the local variable with the index 'local' of the function at 'level' on the stack. See also debug.getlocal.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.setlocal)


debug.setmetatable

Lua function

debug.setmetatable

Summary

Sets the metatable for an object

Prototype

object = debug.setmetatable (object, table)

Description

Sets the metatable for the given object to the given table (which can be nil).

Bypasses the check for the "__metatable" entry.

Returns the object.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setupvalue (Sets an upvalue for a function)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.setmetatable)


debug.setupvalue

Lua function

debug.setupvalue

Summary

Sets an upvalue for a function

Prototype

debug.setupvalue (function, upvalue, value)

Description

Similar to debug.setlocal, sets the values of the upvalue for the nominated function. See also debug.getupvalue.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.traceback (Returns a string with a traceback of the stack call)

(Help topic: lua=debug.setupvalue)


debug.traceback

Lua function

debug.traceback

Summary

Returns a string with a traceback of the stack call

Prototype

s = debug.traceback ( [thread,] message [, level])

Description

Returns a string with a traceback of the stack call. An optional message string is prepended to the beginning of the traceback message.

function f ()

  function g ()

  print (debug.traceback ("traceback in g"))

  end -- g

  g ()

end -- f

f ()

 -->

traceback in g

stack traceback:

        stdin:3: in function `g'

        stdin:6: in function `f'

        stdin:1: in main chunk

        [C]: ?

You can optionally supply a thread (coroutine) to be traced. This is useful if you get an error after calling coroutine.resume.

An  optional level number tells at which level to start the tracekback - the default is 1 which is the function calling traceback.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 debug.debug (Enters interactive debugging)

 debug.getfenv (Returns the environment of an object)

 debug.gethook (Returns the current hook settings)

 debug.getinfo (Returns a table with information about a function)

 debug.getlocal (Returns name and value of a local variable)

 debug.getmetatable (Returns the metatable of the given object)

 debug.getregistry (Returns the registry table)

 debug.getupvalue (Returns the name and value of an upvalue)

 debug.setfenv (Sets the environment of an object)

 debug.sethook (Sets a debug hook function)

 debug.setlocal (Sets the value of the local variable)

 debug.setmetatable (Sets the metatable for an object)

 debug.setupvalue (Sets an upvalue for a function)

(Help topic: lua=debug.traceback)


do

You can use do ... end to make a "block". This can be useful if you want to have a local variable limited in scope, eg.

do

  local foo = 22

  -- use foo here

end -- of do

Also you need to use "do ... end" if you want to put a return inside the middle of a function (eg. for testing), like this:

do return end

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=do)


dofile

Lua function

dofile

Summary

Executes a Lua file

Prototype

val = dofile (filename)

Description

Opens the named file, parses and executes its contents as a Lua chunk.

Raises errors if they occur. Returns any value returned by the chunk.

For example:

dofile ("myfile.lua")

Using dofile is the same as:

function dofile (filename)

  local f = assert (loadfile (filename))

  return f ()

end -- dofile

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=dofile)


error

Lua function

error

Summary

Raises an error message

Prototype

error (message, level)

Description

Raises an error with the supplied message. Never returns. If a level is supplied the error points to the current function (level 1 or nil), the parent function (level 2) and so on.

error ("Insufficient funds") --> error raised: "Insufficient funds"

If you are writing a "validation function" that checks things passed to it, you would normally make the level 2, so that the error message points to the line that calls the validator, rather than the validator itself.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=error)


f:close

Lua function

f:close

Summary

Closes a file

Prototype

f:close ()

Description

Closes the file f.

f:close () -- closes the file descriptor f

If the close was successful the function returns true.

If the file cannot be closed the function returns 3 things:

•	nil

•	An error message (string)

•	An error code (number)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:close)


f:flush

Lua function

f:flush

Summary

Flushes outstanding data to disk

Prototype

f:flush ()

Description

Flushes outstanding data to disk.

f:flush () -- save everything

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:flush)


f:lines

Lua function

f:lines

Summary

Returns an iterator function for reading the file line-by-line

Prototype

it = f:lines ()

Description

Returns an iterator function that reads the open file line-by-line.

At end of file, returns nil.

It does not close the file.

f = io.input ("test.txt")

for line in f:lines () do

  print (line)

end

f:close ()  -- close that file now

 --> Entire contents of file listed

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:lines)


f:read

Lua function

f:read

Summary

Reads the file according to the specified formats

Prototype

v1, v2 ... = f:read (format1, format2, ...)

Description

Reads the file f according to the given formats. Each format returns a string, a number, or nil and an error code if it fails (see below). The formats are:

•	*n - reads a number and returns it

•	*a - reads the entire file from the current position

•	*l - (default) - reads the next line, returns nil on EOF

•	number - returns a string with up that many characters in it, or nil on EOF

f = io.input ("test.txt")

repeat

  s = f:read ("*l") -- read one line

  if s then  -- if not end of file (EOF)

   print (s) -- print that line

  end

until not s  -- until end of file

f:close ()  -- close that file now

If the file cannot be read the function returns 3 things:

•	nil

•	An error message (string)

•	An error code (number)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:read)


f:seek

Lua function

f:seek

Summary

Sets and gets the current file position

Prototype

n = f:seek (whence, offset)

Description

Sets and gets the current file position.

f:seek () --> returns the current file position

When setting a position you can supply a string which is one of:

•	"set" - from beginning of file

•	"cur" - from current position

•	"end" - from end of file

The offset is a number from the base position.

f:seek ("set", 0)     -- go to start of file

f:seek ("end", -100)  -- go to 100 bytes from end of file

f:seek ("cur", 50)    -- go forwards 50 bytes

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:seek)


f:setvbuf

Lua function

f:setvbuf

Summary

Sets the buffering mode for an output file

Prototype

f:setvbuf (mode, size)

Description

Sets the buffering mode for an output file. There are three available modes, which are supplied as strings:

•	"no": no buffering; the result of any output operation appears immediately.

•	"full": full buffering; output operation is performed only when the buffer is full (or when you explicitly flush the file (see io.flush)).

•	"line": line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device).

For the last two cases, size specifies the size of the buffer, in bytes. The default is an appropriate size.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:setvbuf)


f:write

Lua function

f:write

Summary

Writes to a file

Prototype

f:write (v1, v2, v3, ...)

Description

Writes arguments to the file. They must be strings or numbers.

f:write ("hi there", 42, "some more data")

If the write was successful the function returns true.

If the file cannot be written the function returns 3 things:

•	nil

•	An error message (string)

•	An error code (number)

A sensible thing to do would be to check the return code like this:

assert (f:write ("hi there", 42, "some more data"))

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=f:write)


for (generic)

The generic for lets you loop under the control of an iterator, eg.

for key, value in pairs (my_table) do

  print (key, value)

end

The keyword in distinguishes the "generic for" from the "numeric for".

The "generic for" requires three expressions after the word "in" (which might be supplied by a function call such as pairs or ipairs):

•	An iterator function: "f"

•	A state value: "s"

•	An initial value of the iterator variable: "i"

The equivalent of using pairs (my_table) is to do this:

for key, value in next, my_table, nil do

  print (key, value)

end

In this case "next" is the iterator function, my_table is the state value, and nil is the initial value to be passed to the iterator.

If you want to leave the loop from inside you can use a break statement.

You should not attempt to change the loop control variable (the first value returned). Doing so will lead to undefined results.

You don't normally need to be too concerned about the inner details of the "generic for". Often it is used to traverse tables by using the functions pairs or ipairs which return the correct iterators and initial values. For example:

t = { "every", "good", "boy", "deserves", "fruit" }

for key, value in pairs (t) do

  print (key, value)

end -- for

Results:

1 every

2 good

3 boy

4 deserves

5 fruit

More specifically what happens in the generic "for" is:

•	The three expressions are evaluated once before the loop starts. The first argument must be a function (the iterator function).

•	The iterator function is called with both the state "s" and the iterator variable "i".

The state might be a table we are traversing, and the iterator variable might be how far through that table we are.

In effect:

var1, var2, var3 = f (s, i)

•	The first value returned by the iterator function becomes the iterator variable for the next round.

•	If the first value returned by the iterator function is nil the loop terminates.

•	Otherwise the body of the loop executes and then the process (of calling the iterator function onwards) is repeated.

The "next" function is an example of an iterator function. It takes a table and current key, and returns the key/value pair of the next entry. The current key can then be used to get the next one again, and so on. Since the "next" function returns the first key in the table if the "current key" is nil, then we initially start off with nil as the iterator variable.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=for (generic))


for (numeric)

The numeric for lets you loop a specific number of times, eg.

for var = start, finish, step do

  some_action ()

end

The three expressions are evaluated once before the loop starts. "start" is the initial value, "finish" is the limit of the loop, and "step" is what to add after each iteration. For example:

for i = 1, 10, 2 do

  print (i) --> 1, 3, 5, 7, 9

end

for i = 10, 1, -3 do

  print (i) --> 10, 7, 4, 1

end

for i = 1, 5 do

  print (i) --> 1, 2, 3, 4, 5

end

The "loop control" variable (i in the examples above) is only visible inside the loop. It is a mistake to try to access it outside the loop. If you must remember what the loop control variable was when exiting a loop, save it in another variable.

You should not attempt to change the loop control variable. Doing so will lead to undefined results.

If you want to leave the loop from inside you can use a break statement.

More specifically what happens in the numeric "for" is:

•	The three control expressions (start, finish, step) are evaluated once and stored into local variables (start variable, finish variable, step variable). These evaluations must result in numbers or an error is raised. If omitted, the step variable is assumed to be one.

•	The loop control variable (var) is set to the start variable.

•	If the step variable is positive, then the loop control variable is tested to see if it is less than, or equal to, the finish variable. If not, the loop exits.

•	If the step variable is negative or zero, then the loop control variable is tested to see if it is greater than, or equal to, the finish variable. If not, the loop exits.

•	The loop body is now executed.

•	The step variable is added to the loop control variable.

•	Control passes back to the start of the loop to test the loop control variable again.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=for (numeric))


function

The function keyword declares a Lua function (functions can also be written in C).

Functions take zero or more arguments (which become local variables inside the function), like this:

function foo (a, b, c)

  return a + b + c

end -- function foo

If you don't require arguments you still need the brackets:

function foo ()

  print "hi there"

end -- function foo

If the caller does not supply all the argument values, the extra ones are set to nil.

Functions can also be declared in an assignment statement like this:

foo = function (a, b, c)

  return a + b + c

end -- function

This is equivalent to the earlier example.

Functions can return multiple results (see the return statement for more details).

A special form of function argument is the "..." syntax which represents "a variable number of arguments". If used, it must be the last (or only) argument in the function argument list.

For example:

function f (...)

  print (select ("#", ...))  --> 4

  print (select (2, ...))    --> 20  30  40

end -- function f

f (10, 20, 30, 40)

This is useful in cases where you want to pass an unknown number of arguments to a function. The select function is useful for extracting out the individual arguments. Also the unpack function can be used to turn the "..." argument into a table.

Functions are called by supplying the function name followed by the arguments (if any) in brackets. Even if there are no arguments you must use the brackets, otherwise you are just assigning the function. For example:

a = f     -- variable a now contains function f

a = f ()  -- calls function f, puts first result (if any) into a

There is an ambiguity in Lua because of the above, so Lua requires the opening bracket to be on the same line as the function. In other words, this is not permitted:

print

 ("hello")

However this is OK:

print (

  "hello")

Functions can be anonymous, that is, just used where a function is required without assigning them to any variable (and thus they don't have a name). For example, to sort some numbers into descending order:

table.sort (  { 22, 33, 44, 66, 99 },

              function (k1, k2) return k2 < k1 end )

for k, v in ipairs (t) do print (v) end

Output:

99

66

44

33

22

In that example, an anonymous table was sorted using an anonymous comparison function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=function)


gcinfo

Lua function

gcinfo

Summary

Returns amount of dynamic memory in use

Prototype

k = gcinfo ()

Description

Returns Kb of dynamic memory in use.

This function is deprecated in Lua 5.1. Use collectgarbage ("count") instead.

print (gcinfo ()) --> 103

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=gcinfo)


getfenv

Lua function

getfenv

Summary

Returns the current environment table

Prototype

t = getfenv (f)

Description

Returns the current environment used by the nominated function f.

f can be a function or a number representing the stack level, where 1 is the currently running function, 2 is its parent and so on.

The environment is where "global" variables are stored.

print (getfenv (1)) --> table: 02072780

print (_G) --> table: 02072780

The default for f is 1 (the current function).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=getfenv)


getmetatable

Lua function

getmetatable

Summary

Returns the metatable for the object

Prototype

t = getmetatable (obj)

Description

Returns metatable for the nominated object, which can be:

•	nil if no metatable

•	the value of the __metatable field of the metatable, if any

•	the metatable of the object

getmetatable (_G) --> nil

In Lua 5.1, all objects can have metatables (not just tables).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=getmetatable)


identifiers

Identifiers in Lua can be any string of letters, digits, and underscores, not beginning with a digit, of any length. For example:

a   b   monster    abc876    _foo   a_variable_with_a_long_name

You should avoid using identifiers starting with an underscore followed by upper-case letters, as these are reserved for Lua variables such as _VERSION.

Lua is case-sensitive, so foo and FOO are different identifiers.

Identifiers cannot be reserved words, these words are reserved:

•	and

•	break

•	do

•	else

•	elseif

•	end

•	false

•	for

•	function

•	if

•	in

•	local

•	nil

•	not

•	or

•	repeat

•	return

•	then

•	true

•	until

•	while

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=identifiers)


if / then / else

You can use if condition then ... end to test a condition and execute code conditionally, eg.

if button_pressed then

  start_motor ()

end  -- if button pressed

If you want to do something else if the condition is not true you can use an else clause:

if button_pressed then

  start_motor ()

else

  turn_on_lights ()

end  -- if

For multiple tests you can use elseif which avoids having to use end multiple times:

if action == "heal" then

  heal_player ()

elseif action == "sleep" then

  goto_sleep ()

elseif action == "attack" then

  attack_mob ()

else

  print "invalid action"

end  -- if

The only conditions that are false are the values false and nil - every other value is considered true.

You can of course reverse a condition by using not like this:

if not asleep then

  eat_food ()

end  -- if not asleep

It is considered good programming practice to indent the contents of an if statement, to make it clear what parts are being executed conditionally.

It is also a good idea to put a comment on the end indicating what it is the end of (as in the examples above). This is because the keyword end can end if statements, while statements, for statements, do statements, and function bodies.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=if / then / else)


io.close

Lua function

io.close

Summary

Closes a file

Prototype

io.close (f)

Description

Equivalent to f:close (). Without f supplied closes the default output file.

io.close (f) -- closes the file descriptor f

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.close)


io.flush

Lua function

io.flush

Summary

Flushes outstanding data to disk for the default output file

Prototype

io.flush ()

Description

Equivalent to f:flush () for the default output file. Flushes outstanding data to disk.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.flush)


io.input

Lua function

io.input

Summary

Opens filename for input in text mode

Prototype

f = io.input (filename)

Description

Opens filename for input in text mode. Raises an error if it cannot.

If opened OK returns a handle to the opened file, and makes it the default input file.

If called with no argument, returns the handle to the default input file.

If called with a file handle, sets the default input file to that handle.

prev = io.input ()  -- save current input file

f = io.input ("test.txt") --> handle to new file

f:close ()  -- close that file now

io.input (prev) -- restore previous input file

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.input)


io.lines

Lua function

io.lines

Summary

Returns an iterator function for reading a named file line-by-line

Prototype

it = io.lines (filename)

Description

Opens filename for input in text mode. Raises an error if it cannot.

If opened OK returns an iterator function that reads the file line-by-line.

At end of file, returns nil and closes the file.

If filename not supplied, uses the default input file.

for line in io.lines ("test.txt") do

  print (line)

end

 --> Entire contents of file listed

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.lines)


io.open

Lua function

io.open

Summary

Opens a file

Prototype

f = io.open (filename, mode)

Description

Opens a file and returns a file handle for working with it.

Modes can be a string which is:

•	r - read mode

•	w - write mode (overwrites existing)

•	a - append mode (appends to existing)

•	b - binary mode

•	r+ - update mode (existing data preserved)

•	w+ - update mode (existing data erased)

•	a+ - append update mode (existing data preserved, append at end of file only)

If the file cannot be opened this function does not raise an error (unlike io.input and io.output) but returns 3 things:

•	nil

•	An error message (string)

•	An error code (number)

Thus a sensible thing to do is wrap the io.open call with an assert, as in the example:

f = assert (io.open ("test.txt", "r"))  -- open it

s = f:read ("*a")  -- read all of it

print (s)  -- print out

f:close ()  -- close it

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.open)


io.output

Lua function

io.output

Summary

Opens a file for output

Prototype

f = io.output (filename)

Description

Opens filename for output in text mode. Raises an error if it cannot.

If opened OK returns a handle to the opened file, and makes it the default output file.

If called with no argument, returns the handle to the default output file.

If called with a file handle, sets the default output file to that handle.

f = io.output ("test.txt") --> handle to new file

f:write ("some data here") -- write to it

f:close ()  -- close that file now

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.output)


io.popen

Lua function

io.popen

Summary

Creates a pipe and executes a command

Prototype

f = io.popen (command, mode)

Description

Creates a pipe and executes a command. Mode can be one of:

•	"r" - The calling process can read the spawned command’s standard output via the returned stream. This is the default.

•	"w" - The calling process can write to the spawned command’s standard input via the returned stream.

•	"b" - Open in binary mode.

•	"t" - Open in text mode.

However io.popen is not supported under the version compiled into MUSHclient, so don't get too excited. :)

This is an example of using popen under the Linux Lua executable:

 f = assert (io.popen ("ls -l"))

 for line in f:lines() do

   print(line)

 end -- for loop

 f:close()

An alternative to using pipes, if you want to capture operating system output, is to redirect command output to a temporary file, like this:

-- get a temporary file name

n = os.tmpname ()

-- execute a command

os.execute ("dir > " .. n)

-- display output

for line in io.lines (n) do

  print (line)

end

-- remove temporary file

os.remove (n)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.popen)


io.read

Lua function

io.read

Summary

Reads from the default input file

Prototype

v1, v2 ... = io.read ()

Description

Equivalent to io.input ():read (). See f:read for a description.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.read)


io.stderr

Lua function

io.stderr

Summary

File handle for standard error file

Prototype

io.stderr

Description

A file descriptor representing the current stderr (error) file handle.

This is a userdata, not a function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.stderr)


io.stdin

Lua function

io.stdin

Summary

File handle for standard input file

Prototype

io.stdin

Description

A file descriptor representing the current stdin (input) file handle.

This is a userdata, not a function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.stdin)


io.stdout

Lua function

io.stdout

Summary

File handle for standard output file

Prototype

io.stdout

Description

A file descriptor representing the current stdout (output) file handle.

This is a userdata, not a function.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.stdout)


io.tmpfile

Lua function

io.tmpfile

Summary

Returns a handle to a temporary file

Prototype

f = io.tmpfile ()

Description

Returns a handle to a temporary file, opened in update mode. Automatically removed when the program ends.

f = assert (io.tmpfile ()) -- open temporary file

f:write ("some data here")  -- write to it

f:seek ("set", 0) -- back to start

s = f:read ("*a")  -- read all of it back in

print (s)  -- print out

f:close ()  -- close file

-->

some data here

If the file cannot be opened the function returns 3 things:

•	nil

•	An error message (string)

•	An error code (number)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.type (Returns type of file handle)

 io.write (Writes to the default output file)

(Help topic: lua=io.tmpfile)


io.type

Lua function

io.type

Summary

Returns type of file handle

Prototype

s = io.type (f)

Description

Returns a string which is one of:

•	file - an open file handle

•	closed file - a closed file handle

•	nil - not a file handle

f = io.tmpfile ()

print (io.type (f))

f:close ()

print (io.type (f))

-->

file

closed file

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.write (Writes to the default output file)

(Help topic: lua=io.type)


io.write

Lua function

io.write

Summary

Writes to the default output file

Prototype

io.write (v1, v2, ...)

Description

Equivalent to io.output ():write (). See f:write for a description.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 f:close (Closes a file)

 f:flush (Flushes outstanding data to disk)

 f:lines (Returns an iterator function for reading the file line-by-line)

 f:read (Reads the file according to the specified formats)

 f:seek (Sets and gets the current file position)

 f:setvbuf (Sets the buffering mode for an output file)

 f:write (Writes to a file)

 io.close (Closes a file)

 io.flush (Flushes outstanding data to disk for the default output file)

 io.input (Opens filename for input in text mode)

 io.lines (Returns an iterator function for reading a named file line-by-line)

 io.open (Opens a file)

 io.output (Opens a file for output)

 io.popen (Creates a pipe and executes a command)

 io.read (Reads from the default input file)

 io.stderr (File handle for standard error file)

 io.stdin (File handle for standard input file)

 io.stdout (File handle for standard output file)

 io.tmpfile (Returns a handle to a temporary file)

 io.type (Returns type of file handle)

(Help topic: lua=io.write)


ipairs

Lua function

ipairs

Summary

Iterates over a numerically keyed table

Prototype

it, t, 0 = ipairs (t)

Description

Returns an iterator function, the table t, and 0, for use in the generic "for" loop.

for i, v in ipairs (t) do

  -- process loop here (i is the key, v is the value)

end -- for

The iterator function, called repeatedly, returns the key and value pairs for each table item, starting at 1, until it finds the first missing integer key. For example, if keys 1 to 8 are present, and key 9 is nil, it will return the first 8 values. This occurs even if key 10 is present.

In other words, you cannot use ipairs to iterate over a table with "holes" in the key ranges.

If the table has non-numeric keys, there are gaps in the key sequence, or keys do not start at 1, then you need to use pairs (instead of ipairs) to access every item in the table (however this access will not necessarily be in numeric sequence).

Most usually you simply use ipairs to traverse a numerically-keyed table, for example:

t = {

    "the",

    "quick",

    "brown",

    "dog",

   }

for key, value in ipairs (t) do

  print (key, value)

end -- for

Example output:

1 the

2 quick

3 brown

4 dog

In this case the keys (automatically assigned) were 1, 2, 3, 4, and the values were the words in the table.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=ipairs)


keywords

The following keywords are reserved by Lua and thus cannot be used for variable names:

•	and

•	break

•	do

•	else

•	elseif

•	end

•	false

•	for

•	function

•	if

•	in

•	local

•	nil

•	not

•	or

•	repeat

•	return

•	then

•	true

•	until

•	while

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=keywords)


load

Lua function

load

Summary

Loads a chunk by calling a function repeatedly

Prototype

f = load (loader, debugname)

Description

Loads a chunk using function loader to get its pieces. Each call to loader must return a string that concatenates with previous results. A return of nil (or no value) signals the end of the chunk.

If there are no errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.

This could be used to gradually build up a chunk (for example from a network), or to write a preprocessor that reads in a file, preprocess it (like the C preprocessor) and returns the altered code to the Lua interpreter.

The example below shows generating code from entries in a table.

function getcode (t)

local pos = 0

  local function iterator (s)

    pos = pos + 1

    return t [pos]

  end -- iterator

  return iterator

end -- getcode

code = {

  "local a = 1 ",

  "print ('a =', a) ",

  "print 'done.'"

  }

assert (load (getcode (code))) ()

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=load)


loadfile

Lua function

loadfile

Summary

Loads a Lua file and parses it

Prototype

f, err = loadfile (filename)

Description

Opens the named file, parses it and returns the compiled chunk as a function. Does not execute it.

f = assert (loadfile ("myfile.lua"))

f () -- execute function now

Compare to dofile, which executes it as well. That is, dofile is equivalent to the two lines of code above.

If there is an error in the loading process, for example the file is not found, or it is found but has a syntax error, then f will be nil and err will be the nature of the error.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=loadfile)


loadlib

Lua function

loadlib

Summary

Loads a DLL (obsolete in Lua 5.1)

Prototype

loadlib (libraryname, funcname)

Description

This function has been moved in Lua 5.1 to the "package" table. See: package.loadlib.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=loadlib)


loadstring

Lua function

loadstring

Summary

Compiles a string of Lua code

Prototype

f = loadstring (str, debugname)

Description

Parses the string and returns the compiled chunk as a function. Does not execute it.

If the string cannot be parsed returns nil plus an error message.

The optional debugname is used in debug error messages.

f = assert (loadstring ("print 'hello, world'"))

f ()   --> hello, world

You can avoid the intermediate variable "f" in this example by simply putting the brackets on the same line:

assert (loadstring ("print 'hello, world'")) () --> hello, world

If the string was produced by string.dump, loadstring converts it back into the original function.

function f () print "hello, world" end

s = string.dump (f)

assert (loadstring (s)) () --> hello, world

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=loadstring)


local

Local variables are created with the local statement. Their scope is limited to the block where they are declared.

eg.

a = 1 -- global variable

local b = 2 -- local variable

Global variables are stored in the "global environment table" which is generally accessible to all functions. Local variables are only visible to the block in which they are "seen". For example:

function foo ()

  local x = 42  -- x is only visible inside foo

  y = 63  -- global variable y is changed

end -- function foo

In this example if there was another variable "x" somewhere else in the program, it would not be affected by the local variable x inside foo.

Be aware that if you redefine a local variable you get a new one of the same name. Eg.

function foo ()

  local x = 42  -- x is only visible inside foo

  -- do various things here

  local x = 43  -- this is a new variable x, we have not changed the earlier one

end -- function foo

If you want to change an existing local variable, do not use the word local again, eg.

function foo ()

  local x = 42  -- x is only visible inside foo

  -- do various things here

  x = 43  -- we have changed the earlier one

end -- function foo

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=local)


logical operators

The logical operators are and, or, and not. Like control structures, all logical operators consider false and nil as false and anything else (including zero) as true. The operator and returns its first argument if it is false; otherwise, it returns its second argument. The operator or returns its first argument if it is not false, otherwise, it returns its second argument.

Both and and or use short-cut evaluation, that is, they evaluate their second operand only when necessary.

A useful technique is to use the ability of or to return its first argument if it is not false to quickly test if a variable exists. For example:

t = t or {} -- create table if it does not exist

The operator not always returns true or false.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=logical operators)


lpeg.B

Lua function

lpeg.B

Summary

Matches patt n characters behind the current position, consuming no input

Prototype

lpeg.B (patt, n)

Description

Returns a pattern that matches only if the input string matches patt starting n positions behind the current position. (The default value for n is 1.) If the current position is less than or equal to n, this pattern fails.

Like the "and predicate", this pattern never consumes any input, independently of success or failure, and it never produces any capture.

The pattern patt cannot contain any open reference to grammar rules (see grammars).

(This is an experimental feature. There is a good chance it will change in future versions.)

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.B)


lpeg.C

Lua function

lpeg.C

Summary

Creates a simple capture

Prototype

lpeg.C (patt)

Description

Creates a simple capture, which captures the substring of the subject that matches patt. The captured value is a string. If patt has other captures, their values are returned after this one.

For example:

digits = lpeg.R ("09")

hp = lpeg.P ("You gain ") * lpeg.C (digits^1) * " hp."

print (lpeg.match (hp, "You gain 300 hp."))  --> 300

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.C)


lpeg.Carg

Lua function

lpeg.Carg

Summary

Creates an argument capture

Prototype

lpeg.Carg (n)

Description

Creates an argument capture. This pattern matches the empty string and produces the value given as the nth extra argument given in the call to lpeg.match.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Carg)


lpeg.Cb

Lua function

lpeg.Cb

Summary

Creates a back capture

Prototype

lpeg.Cb (name)

Description

This pattern matches the empty string and produces the values produced by the most recent group capture named name.

Most recent means the last complete outermost group capture with the given name. A Complete capture means that the entire pattern corresponding to the capture has matched. An Outermost capture means that the capture is not inside another complete capture.

For example:

open = "[" * lpeg.Cg(lpeg.P"="^0, "init") * "[" * lpeg.P"\n"^-1

close = "]" * lpeg.C(lpeg.P"="^0) * "]"

closeeq = lpeg.Cmt(close * lpeg.Cb("init"), function (s, i, a, b) return a == b end)

string = open * m.C((lpeg.P(1) - closeeq)^0) * close /

  function (o, s) return s end

The open pattern matches [=*[, capturing the repetitions of equal signs in a group named init; it also discharges an optional newline, if present. The close pattern matches ]=*]. The closeeq pattern first matches close; then it uses a back capture to recover the capture made by the previous open, which is named init; finally it uses a match-time capture to check whether both captures are equal. The string pattern starts with an open, then it goes as far as possible until matching closeeq, and then matches the final close. The final function capture simply consumes the captures made by open and close and returns only the middle capture, which is the string contents.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cb)


lpeg.Cc

Lua function

lpeg.Cc

Summary

Creates a constant capture

Prototype

lpeg.Cc ({value})

Description

This pattern matches the empty string and produces all given values as its captured values.

digits = lpeg.R ("09")

hp = lpeg.P ("You gain ") * lpeg.C (digits^1) * " hp." * lpeg.Cc ("life")

print (lpeg.match (hp, "You gain 300 hp."))  --> 300 life

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cc)


lpeg.Cf

Lua function

lpeg.Cf

Summary

Creates a fold capture

Prototype

lpeg.Cf (patt, func)

Description

If patt produces a list of captures C1 C2 ... Cn, this capture will produce the value func(...func(func(C1, C2), C3)..., Cn), that is, it will fold (or accumulate, or reduce) the captures from patt using function func.

This capture assumes that patt should produce at least one capture with at least one value (of any type), which becomes the initial value of an accumulator. (If you need a specific initial value, you may prefix a constant capture to patt.) For each subsequent capture LPeg calls func with this accumulator as the first argument and all values produced by the capture as extra arguments; the value returned by this call becomes the new value for the accumulator. The final value of the accumulator becomes the captured value.

As an example, the following pattern matches a list of numbers separated by commas and returns their addition:

-- matches a numeral and captures its value

number = lpeg.R"09"^1 / tonumber

-- matches a list of numbers, captures their values

list = number * ("," * number)^0

-- auxiliary function to add two numbers

function add (acc, newvalue) return acc + newvalue end

-- folds the list of numbers adding them

sum = lpeg.Cf(list, add)

-- example of use

print(sum:match("10,30,43"))   --> 83

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cf)


lpeg.Cg

Lua function

lpeg.Cg

Summary

Creates a group capture

Prototype

lpeg.Cg (patt [, name])

Description

It groups all values returned by patt into a single capture. The group may be anonymous (if no name is given) or named with the given name.

An anonymous group serves to join values from several captures into a single capture. A named group has a different behavior. In most situations, a named group returns no values at all. Its values are only relevant for a following back capture or when used inside a table capture.

This example parses a list of name-value pairs and returns a table with those pairs:

lpeg.locale(lpeg)

local space = lpeg.space^0

local name = lpeg.C(lpeg.alpha^1) * space

local sep = lpeg.S(",;") * space

local pair = lpeg.Cg(name * "=" * space * name) * sep^-1

local list = lpeg.Cf(lpeg.Ct("") * pair^0, rawset)

t = list:match("a=b, c = hi; next = pi")  --> { a = "b", c = "hi", next = "pi" }

Each pair has the format name = name followed by an optional separator (a comma or a semicolon). The pair pattern encloses the pair in a group pattern, so that the names become the values of a single capture. The list pattern then folds these captures. It starts with an empty table, created by a table capture matching an empty string; then for each capture (a pair of names) it applies rawset over the accumulator (the table) and the capture values (the pair of names). rawset returns the table itself, so the accumulator is always the table.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cg)


lpeg.Cmt

Lua function

lpeg.Cmt

Summary

Creates a match-time capture

Prototype

lpeg.Cmt(patt, function)

Description

Unlike all other captures, this one is evaluated immediately when a match occurs. It forces the immediate evaluation of all its nested captures and then calls function.

The function gets as arguments the entire subject, the current position (after the match of patt), plus any capture values produced by patt.

The first value returned by function defines how the match happens. If the call returns a number, the match succeeds and the returned number becomes the new current position. (Assuming a subject s and current position i, the returned number must be in the range [i, len(s) + 1].) If the call returns false, nil, or no value, the match fails.

Any extra values returned by the function become the values produced by the capture.

For example:

A long string in Lua starts with the pattern [=*[ and ends at the first occurrence of ]=*] with exactly the same number of equal signs. If the opening brackets are followed by a newline, this newline is discharged (that is, it is not part of the string).

To match a long string in Lua, the pattern must capture the first repetition of equal signs and then, whenever it finds a candidate for closing the string, check whether it has the same number of equal signs.

equals = lpeg.P"="^0

open = "[" * lpeg.Cg(equals, "init") * "[" * lpeg.P"\n"^-1

close = "]" * lpeg.C(equals) * "]"

closeeq = lpeg.Cmt(close * lpeg.Cb("init"), function (s, i, a, b) return a == b end)

string = open * lpeg.C((lpeg.P(1) - closeeq)^0) * close / 1

print (string:match ("[===[ foo [=[ bar]=]  ]===]"))  -- test

The open pattern matches [=*[, capturing the repetitions of equal signs in a group named init; it also discharges an optional newline, if present. The close pattern matches ]=*], also capturing the repetitions of equal signs. The closeeq pattern first matches close; then it uses a back capture to recover the capture made by the previous open, which is named init; finally it uses a match-time capture to check whether both captures are equal. The string pattern starts with an open, then it goes as far as possible until matching closeeq, and then matches the final close. The final numbered capture simply discards the capture made by close.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cmt)


lpeg.Cp

Lua function

lpeg.Cp

Summary

Creates a position capture

Prototype

lpeg.Cp ()

Description

It matches the empty string and captures the position in the subject where the match occurs. The captured value is a number.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cp)


lpeg.Cs

Lua function

lpeg.Cs

Summary

Creates a substitution capture

Prototype

lpeg.Cs (patt)

Description

Creates a substitution capture, which captures the substring of the subject that matches patt, with substitutions. For any capture inside patt with a value, the substring that matched the capture is replaced by the capture value (which should be a string). The final captured value is the string resulting from all replacements.

This example does a job somewhat similar to string.gsub. It receives a pattern and a replacement value, and substitutes the replacement value for all occurrences of the pattern in a given string:

function gsub (s, patt, repl)

  patt = lpeg.P(patt)

  patt = lpeg.Cs((patt / repl + 1)^0)

  return lpeg.match(patt, s)

end

As in string.gsub, the replacement value can be a string, a function, or a table.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Cs)


lpeg.Ct

Lua function

lpeg.Ct

Summary

Creates a table capture

Prototype

lpeg.Ct (patt)

Description

This capture creates a table and puts all values from all anonymous captures made by patt inside this table in successive integer keys, starting at 1. Moreover, for each named capture group created by patt, the first value of the group is put into the table with the group name as its key. The captured value is only the table.

The following code splits a string using a given pattern sep as a separator:

If the split results in too many values, it may overflow the maximum number of values that can be returned by a Lua function. In this case, we should collect these values in a table:

function split (s, sep)

  sep = lpeg.P(sep)

  local elem = lpeg.C((1 - sep)^0)

  local p = lpeg.Ct(elem * (sep * elem)^0)   -- make a table capture

  return lpeg.match(p, s)

end

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.Ct)


lpeg.locale

Lua function

lpeg.locale

Summary

Returns a table of patterns matching the current locale

Prototype

lpeg.locale ([table])

Description

Returns a table with patterns for matching some character classes according to the current locale. The table has fields named alnum, alpha, cntrl, digit, graph, lower, print, punct, space, upper, and xdigit, each one containing a correspondent pattern. Each pattern matches any single character that belongs to its class.

If called with an argument table, then it creates those fields inside the given table and returns that table.

For example:

local t = lpeg.locale()

function atwordboundary (p)

  return lpeg.P{

    [1] = p + t.alpha^0 * (1 - t.alpha)^1 * lpeg.V(1)

  }

end

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.locale)


lpeg.match

Lua function

lpeg.match

Summary

Matches a pattern against a string

Prototype

lpeg.match (pattern, subject [, init])

Description

The matching function. It attempts to match the given pattern against the subject string. If the match succeeds, returns the index in the subject of the first character after the match, or the values of captured values (if the pattern captured any value).

An optional numeric argument init makes the match starts at that position in the subject string. As usual in Lua libraries, a negative value counts from the end.

Unlike typical pattern-matching functions, match works only in anchored mode; that is, it tries to match the pattern with a prefix of the given subject string (at position init), not with an arbitrary substring of the subject. So, if we want to find a pattern anywhere in a string, we must either write a loop in Lua or write a pattern that matches anywhere. This second approach is easy and quite efficient.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.match)


lpeg.P

Lua function

lpeg.P

Summary

Converts a value into a pattern

Prototype

lpeg.P (value)

Description

Converts the given value into a proper pattern, according to the following rules:

If the argument is a pattern, it is returned unmodified.

If the argument is a string, it is translated to a pattern that matches literally the string.

eg.

lpeg.P ("You gain")   --> matches "You gain"

If the argument is a non-negative number n, the result is a pattern that matches exactly n characters.

eg.

lpeg.P (5)   --> matches 5 characters

If the argument is a negative number -n, the result is a pattern that succeeds only if the input string does not have n characters: It is equivalent to the unary minus operation applied over the pattern corresponding to the (non-negative) value n.

eg.

lpeg.P (-2)   --> matches if there are not 2 more characters

lpeg.P (-1)   --> matches if there are no more characters (ie. the end of the string)

If the argument is a boolean, the result is a pattern that always succeeds or always fails (according to the boolean value), without consuming any input.

eg.

lpeg.P (true)   --> matches always

lpeg.P (false)   --> matches never

If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string.

If the argument is a table, it is interpreted as a grammar (see below).

-- Grammars --

With the use of Lua variables, it is possible to define patterns incrementally, with each new pattern using previously defined ones. However, this technique does not allow the definition of recursive patterns. For recursive patterns, we need real grammars.

LPeg represents grammars with tables, where each entry is a rule.

The call lpeg.V(v) creates a pattern that represents the nonterminal (or variable) with index v in a grammar. Because the grammar still does not exist when this function is evaluated, the result is an open reference to the respective rule.

A table is fixed when it is converted to a pattern (either by calling lpeg.P or by using it wherein a pattern is expected). Then every open reference created by lpeg.V(v) is corrected to refer to the rule indexed by v in the table.

When a table is fixed, the result is a pattern that matches its initial rule. The entry with index 1 in the table defines its initial rule. If that entry is a string, it is assumed to be the name of the initial rule. Otherwise, LPeg assumes that the entry 1 itself is the initial rule.

As an example, the following grammar matches strings of a's and b's that have the same number of a's and b's:

equalcount = lpeg.P{

  "S";   -- initial rule name

  S = "a" * lpeg.V"B" + "b" * lpeg.V"A" + "",

  A = "a" * lpeg.V"S" + "b" * lpeg.V"A" * lpeg.V"A",

  B = "b" * lpeg.V"S" + "a" * lpeg.V"B" * lpeg.V"B",

} * -1

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.P)


lpeg.print

Lua function

lpeg.print

Summary

Outputs debugging information to stdout

Prototype

lpeg.print (pattern)

Description

Sends debugging information to stdout.

This is not particularly easy to capture in a GUI application. To see it you could execute MUSHclient from the command line, like this:

mushclient.exe > lpeg_output.txt

Then inside MUSHclient use lpeg.print to print a pattern. Close MUSHclient and the file lpeg_output.txt should contain the debugging information.

For example:

00: char 'a'-> FAIL

01: set [(61-7a)]-> FAIL

10: end

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.print)


lpeg.R

Lua function

lpeg.R

Summary

Returns a pattern that matches a range of characters

Prototype

lpeg.R ({range})

Description

Returns a pattern that matches any single character belonging to one of the given ranges. Each range is a string xy of length 2, representing all characters with code between the codes of x and y (both inclusive).

As an example, the pattern lpeg.R("09") matches any digit, and lpeg.R("az", "AZ") matches any ASCII letter.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.R)


lpeg.S

Lua function

lpeg.S

Summary

Returns a pattern that matches a set of characters

Prototype

lpeg.S (string)

Description

Returns a pattern that matches any single character that appears in the given string. (The S stands for Set.)

As an example, the pattern lpeg.S("+-*/") matches any arithmetic operator.

Note that, if the argument is a single character (that is, a string of length 1), then lpeg.P(s) is equivalent to lpeg.S(s) which is equivalent to lpeg.R(s..s). Note also that both lpeg.S("") and lpeg.R() are patterns that always fail.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.S)


lpeg.setmaxstack

Lua function

lpeg.setmaxstack

Summary

Sets the maximum size for the backtrack stack

Prototype

lpeg.setmaxstack (max)

Description

Sets the maximum size for the backtrack stack used by LPeg to track calls and choices. Most well-written patterns need little backtrack levels and therefore you seldom need to change this maximum; but a few useful patterns may need more space. Before changing this maximum you should try to rewrite your pattern to avoid the need for extra space.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.setmaxstack)


lpeg.type

Lua function

lpeg.type

Summary

Tests if a value is a pattern

Prototype

lpeg.type (value)

Description

If the given value is a pattern, returns the string "pattern". Otherwise returns nil.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.V (Creates a non-terminal variable for a grammar)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.type)


lpeg.V

Lua function

lpeg.V

Summary

Creates a non-terminal variable for a grammar

Prototype

lpeg.V (v)

Description

This operation creates a non-terminal (a variable) for a grammar. The created non-terminal refers to the rule indexed by v in the enclosing grammar.

The call lpeg.V(v) creates a pattern that represents the nonterminal (or variable) with index v in a grammar. Because the grammar still does not exist when this function is evaluated, the result is an open reference to the respective rule.

A table is *fixed* when it is converted to a pattern (either by calling lpeg.P or by using it wherein a pattern is expected). Then every open reference created by lpeg.V(v) is corrected to refer to the rule indexed by v in the table.

For example:

-- Grammar

local Exp, Term, Factor = lpeg.V"Exp", lpeg.V"Term", lpeg.V"Factor"

G = lpeg.P{ Exp,

  Exp = lpeg.Ct(Factor * (FactorOp * Factor)^0);

  Factor = lpeg.Ct(Term * (TermOp * Term)^0);

  Term = Number + Open * Exp * Close;

}

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.version (Returns the LPeg version)

(Help topic: lua=lpeg.V)


lpeg.version

Lua function

lpeg.version

Summary

Returns the LPeg version

Prototype

lpeg.version ()

Description

Returns a string with the running version of LPeg.

See Also ...

Topics

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua LPEG library

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 lpeg.B (Matches patt n characters behind the current position, consuming no input)

 lpeg.C (Creates a simple capture)

 lpeg.Carg (Creates an argument capture)

 lpeg.Cb (Creates a back capture)

 lpeg.Cc (Creates a constant capture)

 lpeg.Cf (Creates a fold capture)

 lpeg.Cg (Creates a group capture)

 lpeg.Cmt (Creates a match-time capture)

 lpeg.Cp (Creates a position capture)

 lpeg.Cs (Creates a substitution capture)

 lpeg.Ct (Creates a table capture)

 lpeg.locale (Returns a table of patterns matching the current locale)

 lpeg.match (Matches a pattern against a string)

 lpeg.P (Converts a value into a pattern)

 lpeg.print (Outputs debugging information to stdout)

 lpeg.R (Returns a pattern that matches a range of characters)

 lpeg.S (Returns a pattern that matches a set of characters)

 lpeg.setmaxstack (Sets the maximum size for the backtrack stack)

 lpeg.type (Tests if a value is a pattern)

 lpeg.V (Creates a non-terminal variable for a grammar)

(Help topic: lua=lpeg.version)


math.abs

Lua function

math.abs

Summary

Absolute value

Prototype

v = math.abs (v)

Description

Absolute value of v.

math.abs (-5) --> 5

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.abs)


math.acos

Lua function

math.acos

Summary

Arc cosine

Prototype

v = math.acos (v)

Description

Arc cosine of v. (Inverse operation of math.cos (v)).

math.deg (math.acos (0.5)) --> 60

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.acos)


math.asin

Lua function

math.asin

Summary

Arc sine

Prototype

v = math.asin (v)

Description

Arc sine of v. (Inverse operation of math.sin(v)).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.asin)


math.atan

Lua function

math.atan

Summary

Arc tangent

Prototype

v = math.atan (v)

Description

Arc tangent of v. (Inverse operation of math.tan (v)).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.atan)


math.atan2

Lua function

math.atan2

Summary

Arc tangent of v1/v2

Prototype

v = math.atan2 (v1, v2)

Description

Arc tangent of v1/v2.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.atan2)


math.ceil

Lua function

math.ceil

Summary

Next higher integer value

Prototype

v = math.ceil (v)

Description

Smallest integer >= v

math.ceil (5.5) --> 6

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.ceil)


math.cos

Lua function

math.cos

Summary

Cosine

Prototype

v = math.cos (v)

Description

Cosine of v radians.

math.cos (math.rad (60)) --> 0.5

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.cos)


math.cosh

Lua function

math.cosh

Summary

Hyperbolic cosine

Prototype

v = math.cosh (v)

Description

Hyperbolic cosine of v radians.

math.cosh (math.rad (60)) --> 1.6002868577024

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.cosh)


math.deg

Lua function

math.deg

Summary

Convert from radians to degrees

Prototype

deg = math.deg (r)

Description

Convert v from radians to degrees. Note that math.rad is the inverse operation.

math.deg (1.0471975511966)  --> 60

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.deg)


math.exp

Lua function

math.exp

Summary

Raises e to a power

Prototype

v = math.exp (v)

Description

Compute e to the power v. Note that math.log is the inverse operation.

math.exp (1) --> 2.718281828459 (e itself in this case)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.exp)


math.floor

Lua function

math.floor

Summary

Next smaller integer value

Prototype

v = math.floor (v)

Description

Largest integer <= v

math.floor (5.5) --> 5

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.floor)


math.fmod

Lua function

math.fmod

Summary

The modulus (remainder) of doing: v1 / v2

Prototype

v = math.fmod (v1, v2)

Description

The modulus (remainder) of doing: v1 / v2

math.fmod (100, 22) --> 12

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.fmod)


math.frexp

Lua function

math.frexp

Summary

Break number into mantissa and exponent

Prototype

m, n = math.frexp (v)

Description

The frexp function breaks down the floating-point value (v) into a mantissa (m) and an exponent (n), such that the absolute value of m is greater than or equal to 0.5 and less than 1.0, and v = m * 2^n.

Note that math.ldexp is the inverse operation.

m, n = math.frexp (1.23456e24)

print (m) --> 0.51060204851673

print (n) --> 81

print ( 0.51060204851673 * 2^81 )  --> 1.23456e+024

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.frexp)


math.huge

Lua function

math.huge

Summary

A huge value

Prototype

v = math.huge

Description

The value HUGE_VAL, a value larger than or equal to any other numerical value. Note that this is a number, not a function.

math.huge --> 1.#INF

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.huge)


math.ldexp

Lua function

math.ldexp

Summary

Compute m* 2^n

Prototype

v = math.ldexp (m, n)

Description

The ldexp function returns the value of m * 2^n.

Note that math.frexp is the inverse operation.

math.ldexp (0.51060204851673, 81)   --> 1.23456e+024

math.ldexp (math.frexp (23452345) ) --> 23452345

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.ldexp)


math.log

Lua function

math.log

Summary

Natural log

Prototype

v = math.log (v)

Description

Natural log of v. Note that math.exp is the inverse operation.

math.log (123456) --> 11.723640096265

math.exp (math.log (123456))  --> 123456

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.log)


math.log10

Lua function

math.log10

Summary

Log to the base 10

Prototype

v = math.log10 (v)

Description

Log to the base 10 of v.

math.log10 (123456) --> 5.0915122016278

10 ^ 5.0915122016278 --> 123456.00000001 (slight rounding error)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.log10)


math.max

Lua function

math.max

Summary

The highest of one or more numbers

Prototype

v = math.max (v1, v2, ...)

Description

The highest of one or more numbers.

math.max (4, 8, 100) --> 100

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.max)


math.min

Lua function

math.min

Summary

The lowest of one or more numbers

Prototype

v = math.min (v1, v2, ...)

Description

The lowest of one or more numbers.

math.min (4, 8, 100) --> 4

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.min)


math.modf

Lua function

math.modf

Summary

Returns the integral and fractional part of its argument

Prototype

i, f = math.modf (v)

Description

Returns two numbers, the integral part of v and the fractional part of v

math.modf (10.2) --> 10  0.2

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.modf)


math.pi

Lua function

math.pi

Summary

The value of pi

Prototype

pi = math.pi

Description

A variable representing the value of pi (not a function).

print (math.pi) --> 3.1415926535898

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.pi)


math.pow

Lua function

math.pow

Summary

Raise a number to a power

Prototype

v = math.pow (v1, v2)

Description

v1 raised to the power v2.

math.pow (2, 8) --> 256

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.pow)


math.rad

Lua function

math.rad

Summary

Convert degrees to radians

Prototype

r = math.rad (deg)

Description

Convert v from degrees to radians. Note that math.deg is the inverse operation.

math.rad (60) --> 1.0471975511966

assert (math.pi / 180 == math.rad (1))   --> (they are the same)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.rad)


math.random

Lua function

math.random

Summary

Generate a random number

Prototype

v = math.random (n, u)

Description

With no arguments, returns a random number in the range [0, 1). That is, zero up to but excluding 1.

With 1 argument, returns an integer in the range [1, n]. That is from 1 up to and including n.

With 2 arguments, returns an integer in the range [n, u]. That is from n up to and including u.

Use math.randomseed to seed the generator.

math.random () --> 0.30195013275552 (for example)

math.random (5)  --> (a number from 1 to 5)

math.random (4, 8)  --> (a number from 4 to 8)

Also see the world.MtRand function for random numbers generated by the Mersenne Twister algorithm.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.random)


math.randomseed

Lua function

math.randomseed

Summary

Seeds the random number generator

Prototype

math.randomseed (n)

Description

Seeds the random number generator with an integer. Re-seed with the same number to regenerate the same sequences by calling math.random.

Seeding with os.time () is a common technique to make random numbers different each time. Be aware however that for cryptographic purposes, the time of day is hardly a secret.

math.randomseed (44)    -- fixed random seed

math.randomseed (os.time ())  -- randomize from whatever the time is

Also see the world.MtSrand function for seeding the Mersenne Twister random number generator.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.randomseed)


math.sin

Lua function

math.sin

Summary

Sine

Prototype

v = math.sin (v)

Description

Sine of v radians.

math.sin ( math.rad (30)) --> 0.5

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.sin)


math.sinh

Lua function

math.sinh

Summary

Hyperbolic sine

Prototype

v = math.sinh (v)

Description

Hyperbolic sine of v radians.

math.sinh ( math.rad (30)) --> 0.54785347388804

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sqrt (Square root)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.sinh)


math.sqrt

Lua function

math.sqrt

Summary

Square root

Prototype

v = math.sqrt (v)

Description

Square root of v.

math.sqrt (16) --> 4

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.tan (Tangent)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.sqrt)


math.tan

Lua function

math.tan

Summary

Tangent

Prototype

v = math.tan (v)

Description

Tangent of v radians.

math.tan( math.rad (45)) --> 1

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tanh (Hyperbolic  tangent)

(Help topic: lua=math.tan)


math.tanh

Lua function

math.tanh

Summary

Hyperbolic  tangent

Prototype

v = math.tanh (v)

Description

Hyperbolic tangent of v radians.

math.tanh( math.rad (45)) --> 0.65579420263267

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 math.abs (Absolute value)

 math.acos (Arc cosine)

 math.asin (Arc sine)

 math.atan (Arc tangent)

 math.atan2 (Arc tangent of v1/v2)

 math.ceil (Next higher integer value)

 math.cos (Cosine)

 math.cosh (Hyperbolic cosine)

 math.deg (Convert from radians to degrees)

 math.exp (Raises e to a power)

 math.floor (Next smaller integer value)

 math.fmod (The modulus (remainder) of doing: v1 / v2)

 math.frexp (Break number into mantissa and exponent)

 math.huge (A huge value)

 math.ldexp (Compute m* 2^n)

 math.log (Natural log)

 math.log10 (Log to the base 10)

 math.max (The highest of one or more numbers)

 math.min (The lowest of one or more numbers)

 math.modf (Returns the integral and fractional part of its argument)

 math.pi (The value of pi)

 math.pow (Raise a number to a power)

 math.rad (Convert degrees to radians)

 math.random (Generate a random number)

 math.randomseed (Seeds the random number generator)

 math.sin (Sine)

 math.sinh (Hyperbolic sine)

 math.sqrt (Square root)

 math.tan (Tangent)

(Help topic: lua=math.tanh)


module

Lua function

module

Summary

Creates a Lua module

Prototype

module (name, ···)

Description

Creates a module. This is intended for use with external "package" files, however it can be used internally as shown in the example below. The module effectively has its own global variable space (because module does a setfenv) so that any functions or variables used in the module are local to the module name (for example, foo.add in the example below).

If there is a table in package.loaded[name], this table is the module. Thus, if the module has already been requested (by a require statement) another new table is not created.

Otherwise, if there is a global table t with the given name, this table is the module.

Otherwise creates a new table t and sets it as the value of the global name and the value of package.loaded[name].

This function also initializes t._NAME with the given name, t._M with the module (t itself), and t._PACKAGE with the package name (the full module name minus last component).

Finally, module sets t as the new environment of the current function and the new value of package.loaded[name], so that require returns t.

The example below shows the creation of the module "foo". In practice you would probably put the contents of the "test" function into a separate file, and then: require "test"

The nice thing about this approach is that nothing inside the module will "pollute" the global namespace, excepting the module name itself (foo in this case). Internally inside the module functions can call each other without having to use the package name (eg. add could call subtract without using foo.subtract).

You can make a "private" function inside the "foo" package by simply putting "local" in front of the function name.

function test ()

  local print = print  --> we need access to this global variable

  module "foo"  --> create the module now

  function add (a, b)

    return a + b

  end -- add

  function subtract (a, b)

    return a - b

  end -- subtract

  function hello (s)

    print ("hello", s)

  end -- hello

end -- function test

test ()  -- install module

foo.hello ("world")   --> hello	world

print (foo.add (2, 3))  --> 5

print (foo.subtract (7, 8))  --> -1

print (package.loaded["foo"]) --> table: 003055F0

print (foo)  --> table: 003055F0

for k, v in pairs (foo) do

  print (k, v)

end -- for

-->

_M	table: 003055F0

_NAME	foo

_PACKAGE

hello	function: 00305810

subtract	function: 00305760

add	function: 00305780

After the module has been created, we can see that:

foo._M is foo itself (ie. the module)

foo._NAME is "foo"

foo._PACKAGE is an empty string (if the module was "foo.bar" then _PACKAGE would be "foo.")

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=module)


next

Lua function

next

Summary

Returns next key / value pair in a table

Prototype

index, value = next (table, index)

Description

Traverses all entries in a table. Returns the next index, value pair. If index is nil (the default), returns the first pair. When called with the last index of the table (or with an index of nil for an empty table), returns nil.

Only non-nil values are returned. Order is not specified (eg. is not necessarily alphabetic sequence). Behaviour is undefined if you assign values to non-existent fields during the traversal. You may however modify or delete existing fields.

t = { "hello", "world" }

for k, v in next, t do

  print (k, v)

end

-->

1 hello

2 world

See also the pairs function, which uses next. The above code could be written as:

for k, v in pairs (t) do

  print (k, v)

end

If you want to know if a table is empty, or not, you can test:

if next (t) == nil then

  -- table t is empty

end -- if empty

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=next)


os.clock

Lua function

os.clock

Summary

Amount of elapsed/CPU time used (depending on OS)

Prototype

cpu = os.clock ()

Description

Returns the approximate amount of CPU time used by the current process in seconds.

print (os.clock () / 60 / 60) --> 34.381006944444 (hours)

WARNING - under Linux and Mac OS os.clock returns the CPU time used.  However, under Windows it returns the elapsed time that the process has been running (not the CPU time used). This is because the operating system call "clock" works differently under Windows.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.clock)


os.date

Lua function

os.date

Summary

Formats a date/time string

Prototype

s = os.date (format, time)

Description

Returns a string with the date and time formatted according to the format given. If no time is supplied defaults to the current time.

The format string can consist of "*t" on its own, or literal strings, mixed with the following directives:

%a - Abbreviated weekday name (eg. Wed)

%A - Full weekday name (eg. Wednesday)

%b - Abbreviated month name (eg. Sep)

%B - Full month name (eg. September)

%c - Date and time representation appropriate for locale (eg. 23/04/07 10:20:41)

         (Standard date and time string ) - see below for using os.setlocale to get the correct locale.

%d - Day of month as decimal number (01 - 31)

%H - Hour in 24-hour format (00 - 23)

%I - Hour in 12-hour format (01 - 12)

%j - Day of year as decimal number (001 - 366)

%m - Month as decimal number (01 - 12)

%M - Minute as decimal number (00 - 59)

%p - Current locale’s A.M./P.M. indicator for 12-hour clock (eg. AM/PM)

%S - Second as decimal number (00 - 59)

%U - Week of year as decimal number, with Sunday as first day of week 1 (00 - 53)

%w - Weekday as decimal number (0 - 6; Sunday is 0)

%W - Week of year as decimal number, with Monday as first day of week 1 (00 - 53)

%x - Date representation for current locale (Standard date string)

%X - Time representation for current locale (Standard time string)

%y - Year without century, as decimal number (00 - 99)  (eg. 07)

%Y - Year with century, as decimal number (eg. 2007)

%Z - Time-zone name or abbreviation; no characters if time zone is unknown

%% - Percent sign

If you use "*t" you get a table consisting of:

•	sec  (0 to 59)

•	min  (0 to 59)

•	hour (0 to 23)

•	day  (1 to 31)

•	month (1 to 12)

•	year  (1900 onwards)

•	wday (Sunday is 1, Monday is 2 etc.)

•	yday (January 1st is 1, etc.)

•	isdst (true if Daylight Savings Time)

Examples:

print (os.date ("%x")) --> 25/04/07

print (os.date ("%c")) --> 25/04/07 10:10:05

print (os.date ("%A, %m %B %Y")) --> Wednesday, 04 April 2007

t = os.date ("*t") --> produces a table like this:

  t.sec=18

  t.min=13

  t.hour=10

  t.day=25

  t.month=4

  t.year=2007

  t.wday=4

  t.yday=115

  t.isdst=false

Locale note - it seems that doing this helps set the locale appropriately:

os.setlocale ("", "time")

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.date)


os.difftime

Lua function

os.difftime

Summary

Calculates a time difference in seconds

Prototype

n = os.difftime (t1, t2)

Description

Returns the number of seconds from time t1 to time t2.

In other words, the result is t1 - t2.

tstart = os.time ()

-- do something lengthy here ..

tend = os.time ()

print (os.difftime (tend , tstart)) --> 3

When using MUSHclient (ie. this is not standard Lua) you can get better resolution by using GetInfo (which uses the Windows "high performance" timer), like this:

tstart = GetInfo (232)  -- get high-resolution timer value

-- do something lengthy here ..

tend = GetInfo (232)

print (string.format ("Time taken = %1.3f seconds", tend - tstart))

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.difftime)


os.execute

Lua function

os.execute

Summary

Executes an operating system command

Prototype

status = os.execute (command)

Description

Passes 'command' to the operating system shell for execution. Returns a status code.

status = os.execute ("dir") --> (directory listing whizzes by)

Here is a method of capturing the output to a file, and reading it in:

-- get a temporary file name

n = os.tmpname ()

-- execute a command

os.execute ("dir > " .. n)

-- display output

for line in io.lines (n) do

  print (line)

end

-- remove temporary file

os.remove (n)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.execute)


os.exit

Lua function

os.exit

Summary

Attempts to terminate the process

Prototype

os.exit (n)

Description

Terminates the host program with the return code n (in standard Lua).

However, os.exit is does not do that in MUSHclient. It will raise an error if called ("'os.exit' not implemented in MUSHclient"). This is because doing an immediate exit bypasses all checks to save open documents, save plugin states, and so on.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.exit)


os.getenv

Lua function

os.getenv

Summary

Returns an operating system environment variable

Prototype

os.getenv (v)

Description

Returns the environment variable v, or nil if undefined.

print (os.getenv ("PATH")) --> (my PATH variable)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.getenv)


os.remove

Lua function

os.remove

Summary

Deletes a file

Prototype

ok, message = os.remove (filename)

Description

Deletes the file. On success, returns true.

If it cannot, it returns nil followed by an error message.

os.remove ("test.txt") --> true

ok, err = os.remove ("test.txt") --> nil, test.txt: No such file or directory

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.remove)


os.rename

Lua function

os.rename

Summary

Renames a file

Prototype

ok, message = os.rename (oldname, newname)

Description

Renames a file. On success, returns true.

If it cannot, it returns nil followed by an error message.

os.rename("test.txt", "test2.txt") --> true

os.rename("test.txt", "test2.txt") --> nil, test.txt: File exists

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.rename)


os.setlocale

Lua function

os.setlocale

Summary

Sets the current locale to the supplied locale

Prototype

name = os.setlocale (locale, category)

Description

Sets the current locale to the supplied locale. Category, which is optional, is a string which is one of:

•	"all" (the default)

•	"collate"

•	"ctype"

•	"monetory"

•	"numeric"

•	"time"

Returns the name of the new locale, or nil if invalid.

print (os.setlocale ("en", "collate")) --> English_United States.1252

Hint: I found that in Australia, the default in Lua was to use the USA time format (MM/DD/YY) rather than the local format (DD/MM/YY) when displaying dates with os.date. This line seemed to fix that:

print (os.setlocale ("", "time")) --> English_Australia.1252

According to the help file "If locale points to an empty string, the locale is the implementation-defined native environment.". Thus the empty locale string seemed take the country default.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.time (Returns the current time or calculates the time in seconds from a table)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.setlocale)


os.time

Lua function

os.time

Summary

Returns the current time or calculates the time in seconds from a table

Prototype

time = os.time (t)

Description

Returns the current time if no argument supplied. The time is in seconds from the start of the current epoch.

On Windows, the function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time, according to the system clock.

If an argument is supplied it must be a table with at least the entries:

•	year

•	month

•	day

The table can also have the entries:

•	hour

•	min

•	sec

•	isdst

This table can be produced by calling: os.date ("*t")

print (os.time { year = 2004, month = 8,

                 day = 30, hour = 6, min = 32, sec = 1, dst = true }) --> 1093811521

print (os.date ("%x %X", 1093811521))  --> 30/08/04 06:32:01

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.tmpname (Returns a name for a temporary file)

(Help topic: lua=os.time)


os.tmpname

Lua function

os.tmpname

Summary

Returns a name for a temporary file

Prototype

s = os.tmpname ()

Description

Returns a string with a name for a temporary file. Considered unsafe in an untrusted environment because someone may substitute a different file for the one whose name is returned to you, in the small window of time between obtaining the file name, and opening the file.

print (os.tmpname ()) --> /temp/s56.2

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 os.clock (Amount of elapsed/CPU time used (depending on OS))

 os.date (Formats a date/time string)

 os.difftime (Calculates a time difference in seconds)

 os.execute (Executes an operating system command)

 os.exit (Attempts to terminate the process)

 os.getenv (Returns an operating system environment variable)

 os.remove (Deletes a file)

 os.rename (Renames a file)

 os.setlocale (Sets the current locale to the supplied locale)

 os.time (Returns the current time or calculates the time in seconds from a table)

(Help topic: lua=os.tmpname)


package.config

Lua function

package.config

Summary

Package configuration string

Prototype

package.config

Description

This is a string containing the various character used by the package manager to handle loading packages:

The default entries are:

\  --> directory seperator

;  --> path seperator

?  --> path mark

!  --> execution directory

-  --> ignore mark - ignore everything before it to build a function name

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.config)


package.cpath

Lua function

package.cpath

Summary

Search path used for loading DLLs using the "require" function

Prototype

package.cpath

Description

This is a string containing the search path used for loading DLLs when using the "require" function. Default values are:

.\?.dll;!\?.dll;!\loadall.dll

In the above, the package name (eg. "socket") will replace the "?" characters and the current executable pathname (eg. "c:\mushclient") will replace the "!" characters.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.cpath)


package.loaded

Lua function

package.loaded

Summary

Table of loaded packages

Prototype

package.loaded

Description

A table of the packages that are already loaded. Built-in packages (eg. table, string) are also in this table.

table.foreach (package.loaded, print)

  -->

string	table: 00301370

package	table: 00302C70

_G	table: 00300200

os	table: 003034E0

table	table: 00302560

math	table: 00304B00

coroutine	table: 00301040

debug	table: 00304340

io	table: 00303D60

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.loaded)


package.loaders

Lua function

package.loaders

Summary

Table of package loaders

Prototype

package.loaders

Description

This is a table of the loaders that Lua calls when handling the "require" function. As defined in the source code they are presently done in this order:

•	Preloader

•	Lua loader

•	DLL loader

•	All-in-one loader

You could conceivable alter the behaviour of the "require" function be re-odering the loaders (eg. load DLLs before Lua code), deleting a loader, or adding your own.

The existing loaders appear to push a string describing what files they failed to load (which you can see if you load a non-existant package), so any loaders you write yourself could return the loaded function on success, and an error string on failure.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.loaders)


package.loadlib

Lua function

package.loadlib

Summary

Loads a dynamic link library (DLL)

Prototype

f = package.loadlib (libraryname, funcname)

Description

Loads the dynamic library (DLL), and tries to find the entrypoint named "funcname".

On success returns the function funcname.

On failure returns nil plus 2 error messages.

The error might be "The specified module could not be found." if the DLL is not found. You may also get this message if the DLL is dependant on another DLL and that other DLL cannot be found. Use a "dependency checker" to see what DLLs the target DLL might require. If you are certain that the DLL you are requesting exists, then the problem is probably a dependency.

The error might be "The specified procedure could not be found." if the function is not found in the DLL. You may also get this message if the DLL is dependant on another DLL and some entry points in that other DLL cannot be found. Use a "dependency checker" to see whether all required entry points have been resolved. If you are certain that the entry point that you are requesting exists in the target DLL, then the problem is probably a dependency from the target DLL to another DLL.

You would normally then execute the function (as in the example below) to get it to install the Lua functions into the script space.

f = assert (package.loadlib ("luacom.dll", "luacom_openlib"))

f () -- execute function: luacom_openlib

Or, more briefly:

assert (package.loadlib ("luacom.dll", "luacom_openlib")) ()

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.loadlib)


package.path

Lua function

package.path

Summary

Search path used for loading Lua code using the "require" function

Prototype

package.path

Description

This is a string containing the search path used for loading Lua code when using the "require" function. Default values are:

.\?.lua;!\lua\?.lua;!\lua\?\init.lua;!\?.lua;!\?\init.lua

In the above, the package name (eg. "socket") will replace the "?" characters and the current executable pathname (eg. "c:\mushclient") will replace the "!" characters.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.preload (A table of special function loaders)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.path)


package.preload

Lua function

package.preload

Summary

A table of special function loaders

Prototype

package.preload

Description

A table of functions that can be used as loaders. If you want to make a special loader for your package you can insert it into the package.preload table. For example:

package.preload ["foo"] = function () print "loading foo" end

require "foo"  --> loading foo

In this example, when we required the package foo, the function was called.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.seeall (Sets a metatable for the module so it can see global variables)

(Help topic: lua=package.preload)


package.seeall

Lua function

package.seeall

Summary

Sets a metatable for the module so it can see global variables

Prototype

package.seeall (module)

Description

Sets a metatable for module with its __index field referring to the global environment, so that this module inherits values from the global environment. To be used as an option to function module. For example:

module ("foo", package.seeall)

The module code applies the function package.seeall to the new package (foo) and thus now package foo can access global variables.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 package.config (Package configuration string)

 package.cpath (Search path used for loading DLLs using the "require" function)

 package.loaded (Table of loaded packages)

 package.loaders (Table of package loaders)

 package.loadlib (Loads a dynamic link library (DLL))

 package.path (Search path used for loading Lua code using the "require" function)

 package.preload (A table of special function loaders)

(Help topic: lua=package.seeall)


pairs

Lua function

pairs

Summary

Traverse all items in a table

Prototype

next, t, nil = pairs (t)

Description

Returns the 'next' function, the table t, and nil, for use in a for loop.

t = { "hello", "world" }

for k, v in pairs (t) do

  print (k, v)   -- k is the key, v is the value

end

Compare to ipairs which only traverses numerically-keyed entries.

Use the pairs function to traverse any table. The table will not necessarily be accessed in alphabetic (or any particular) order.

You must not add additional entries to the table during traversal. Doing so is undefined (that is, the script may crash or loop).

You are permitted to delete items from the table during traversal. In other words, if you find an item you want to delete you may assign nil to it, to delete it.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=pairs)


pcall

Lua function

pcall

Summary

Calls a function in protected mode

Prototype

ok, result [ , result2 ...] = pcall (f, arg1, arg2, ...)

Description

Calls function f with the supplied arguments in protected mode. Catches errors and returns:

On success:

•	true

•	function result(s) - may be more than one

On failure:

•	false

•	error message

function f (v)

  return v + 2

end -- f

a, b = pcall (f, 1)

print (a, b) --> true 3

a, b = pcall (f, "a")

print (a, b)  --> false   stdin:2: attempt to perform arithmetic on local `v' (a string value)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=pcall)


precedence

Operator precedence specifies which operations are done first (for example, multiply before add).

You can use parentheses to change the precedence of an expression.

From highest to lowest the precedence is:

^

not #   - (unary)

*   /   %

+   -

..

<   >   <=  >=  ~=  ==

and

or

The # operator is the "length" operator which can be applied to things like strings and tables (eg. #"nick" is 4).

All binary operators are left-associative, except for "^" (exponentiation) and ".." (concatenation) which are right-associative.

What this means is that for left-associative operators at the same level (eg. + and -) they are grouped from left to right. Thus:

a - b + c

is the same as:

(a - b) + c

So for example:

3 - 1 + 5  --> 7 (not -3)

However for concatenation:

a .. b .. c

is the same as:

a .. (b .. c)

And for exponentiation:

a^b^c

is the same as:

a^(b^c)

For example:

print (4^3^2)  --> 262144 (not 4096)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=precedence)


print

Lua function

print

Summary

Prints its arguments

Prototype

print (a1, a2, a3, ...)

Description

Prints its arguments to stdout (or the output window in the case of MUSHclient, using world.Note), formatted by calling 'tostring'. Not intended for formatted output, but rather for debugging. Each argument is separated by a space.

print ("Hello", "world", 123, assert) --> Hello world 123 function: 02071C00

For formatted output, see string.format.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=print)


rawequal

Lua function

rawequal

Summary

Compares two values for equality without invoking metamethods

Prototype

b = rawequal (v1, v2)

Description

Returns a boolean depending on v1 == v2 without invoking any table metamethods.

print (rawequal (3, 3))) --> true

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=rawequal)


rawget

Lua function

rawget

Summary

Gets the value of a table item without invoking metamethods

Prototype

v = rawget (table, index)

Description

Gets the real value of table [index] without invoking metamethods. Index should not be nil.

print (rawget (_G, "Note")) --> nil

print (rawget (world, "Note"))  --> function: 02058190

print (Note) --> function: 02058190

This example shows that the Note function is not really in the global environment. MUSHclient adds a metamethod to pull it from the "world" table.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=rawget)


rawset

Lua function

rawset

Summary

Sets the value of a table item without invoking metamethods

Prototype

rawset (table, index, value)

Description

Sets the value of table [index] to value, without invoking metamethods. 'table' must be a table, and 'index' must not be nil.

rawset (_G, "test", 42)

print (test) --> 42

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=rawset)


re:exec

Lua function

re:exec

Summary

Matches a regexp to a string, returning offsets

Prototype

start, end, offsets = re:exec (string, pos, flags)

Description

This takes a regular expression object compiled previously with rex.new, and matches it against a target string. It takes the same arguments are re:match, however the table returned as the 3rd result consists of pairs of offsets, rather than the strings themselves.

For example:

re = rex.new ("(.+) goes (.+)")

s, e, t = re:exec ("Nick goes East")

print (s, e)  --> 1 14

table.foreach (t, print) --> see below

Output from table.foreach:

1 1

2 4

3 11

4 14

In this case we see that the first capture was from columns 1 to 4, and the second capture was from columns 11 to 14.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:gmatch (Matches a regexp to a string, applying a function)

 re:match (Matches a regexp to a string)

 rex.flags (Returns a table of PCRE flags)

 rex.new (Compiles a regular expression)

(Help topic: lua=re:exec)


re:gmatch

Lua function

re:gmatch

Summary

Matches a regexp to a string, applying a function

Prototype

result = re:gmatch (string, fun, count, flags)

Description

The gmatch function:

•	Tries to match the regex re against string up to count times (or as many as possible if count is either not given or is not a positive number), subject to execution flags "flags".

•	Each time there is a match, fun is called as fun (m, t), where m is the matched string and t is a table of substring matches (this table contains false in the positions where the corresponding sub-pattern did not match.).

•	If fun returns a true value, then gmatch immediately returns.

•	gmatch returns the number of matches made.

re = rex.new ("(\[A-Za-z\]+)")

n = re:gmatch ("Nick goes East", function (m, t) print (m) end )

print (n) --> 3

Output from function during execution:

Nick

goes

East

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:exec (Matches a regexp to a string, returning offsets)

 re:match (Matches a regexp to a string)

 rex.flags (Returns a table of PCRE flags)

 rex.new (Compiles a regular expression)

(Help topic: lua=re:gmatch)


re:match

Lua function

re:match

Summary

Matches a regexp to a string

Prototype

start, end, substrings = re:match (string, pos, flags)

Description

This takes a regular expression object compiled previously with rex.new, and matches it against a target string.

The "pos" argument is optional, and specifies a 1-relative starting point for the match. If omitted, the whole string is tested. You can also supply a negative number to count from the right, eg. -10 would start 10 characters from the end of the string.

The "flags" argument is optional, and specifies execution flags, as described above.

Example:

re = rex.new ("(.+) goes (.+)")

s, e = re:match ("Nick goes East")

print (s, e) --> 1 14

If you are planning to do multiple matches against the same regular expression, it is faster to compile once only (ie. do rex.new once), and test multiple times.

However for once-off tests you can combine them both into the same line:

s, e = rex.new ("(.+) goes (.+)"):match ("Nick goes East")

print (s, e) --> 1 14

The third result returned is a table of capture patterns that have been matched.

Example:

re = rex.new ("(?P<who>.+) goes (?P<where>.+)")

s, e, t = re:match ("Nick goes East")

print (s, e) --> 1 14

table.foreach (t, print) --> see below

Output from table.foreach:

1 Nick

2 East

where East

who Nick

This shows that the 2 capture patterns (the things in round brackets) have been captured in the table as index 1 and 2 (first and second pattern) and also under named indices "where" and "who" because we used named capture patterns in the regular expression.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:exec (Matches a regexp to a string, returning offsets)

 re:gmatch (Matches a regexp to a string, applying a function)

 rex.flags (Returns a table of PCRE flags)

 rex.new (Compiles a regular expression)

(Help topic: lua=re:match)


relational operators

Lua provides the following relational operators:

    <   >   <=  >=  ==  ~=

All these operators always result in true or false.

The operator == tests for equality; the operator ~= is the negation of equality.

If the values are different types they are considered different values. For example, "5" (string type) is not the same as 5 (number type).

Tables, userdata and functions are compared by reference. That is they are considered equal only if they are the same underlying object. Thus two tables, which happen to contain the same things, but which were created separately, are considered different.

Note that the equality test is "==", not just "=". Thus this is incorrect:

if a = 5 then  -- wrong! use a == 5 instead

Also note that the inequality test is "~=", not "!=" as used by the C language.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=relational operators)


repeat

You can make code loop by using repeat ... until condition  - the test is done at the end of the loop, so the body of the loop is always executed at least once.

local action

repeat

  action = get_action ()

until action ~= ""

If you want to leave the loop from inside you can use a break statement:

local action

local count = 0

repeat

  action = get_action ()

  count = count + 1

  if count > 5 then

    break

  end -- if

until action ~= ""

The only conditions that are false are the values false and nil - every other value is considered true.

If you want to test at the start of the loop use while instead.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=repeat)


require

Lua function

require

Summary

Loads a module

Prototype

val = require (modname)

Description

Loads the named module.

First checks the table package.loaded to see if it has already been loaded. If so, returns the value there.

Otherwise it tries to find a loader for the module. It tries these things:

•	If the table item package.preload [modname] is a function, that is called as the module loader.

•	Process the variable package.path, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as Lua source files. The first attempt in the default configuration is in the current directory, for modname.lua, then in the executable directory (that is, where MUSHclient executable is, if you are running from MUSHclient), various combinations of subdirectories and file names. To see exactly what tests are being done, just type 'require "foo"' and the error message will show you.

•	Process the variable package.cpath, substituting modname where it has a "?" (that is, ? becomes the name) and then repeatedly attempting to open the files in the list (paths separated by semicolons) as DLLs. This attempts to load various DLLs, again see the package.cpath variable to see which ones exactly, or try a dummy require, as described above. If a DLL is found it attempts to call the function "luaopen_" concatenated with the module name, where dots are replaced by underscores.

•	Finally if all else fails try to load the all-in-one loader (executable-path/loadall.dll) and look for an appropriate function.

Once a loader is found, require calls the loader with a single argument, modname. If the loader returns any value, require assigns the returned value to package.loaded [modname]. If the loader returns no value and has not assigned any value to package.loaded [modname], then require assigns true to this entry. In any case, require returns the final value of package.loaded [modname].

f = require ("test")  --> loads module "test"

Effectively this lets various modules "require" a package, and it will only be loaded once. Also see the description for "module" for ways of effectively setting up a module to work in conjunction with "require".

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=require)


return

The return statement exits the current function, optionally returning values to the caller. For example:

return   -- exit returning no values

return 1, 2, 3, 4  -- exit returning four values

Every function has an implicit return at the end of it, so you don't normally need to put your own, unless you want to return values.

Functions can return multiple values, which can be "captured" by a multiple assignment statement. For example:

function foo ()

  return 1, 2, 3, 4

end -- function foo

a, b, c, d = foo ()  --> assigns the values 1, 2, 3, 4

If a function returns a function call, then multiple values returned by the calling function are returned. For example:

function foo ()

  return 1, 2, 3, 4

end -- function foo

function bar ()

  return foo ()

end -- function bar

print (bar ())  --> 1, 2, 3, 4

If a function returns multiple values and those values are used in an expression list, then the multiple values are adjusted to one value (the first) unless they are used in the last or only place. For example:

function foo ()

  return 1, 2, 3, 4

end -- function foo

print (foo (), 8)  --> 1, 8 (other values discarded)

However:

function foo ()

  return 1, 2, 3, 4

end -- function foo

print (8, foo ())  --> 8, 1, 2, 3, 4 (all values retained)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 string literals (How to write constant strings)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=return)


rex.flags

Lua function

rex.flags

Summary

Returns a table of PCRE flags

Prototype

flag_table = rex.flags ()

Description

This returns a table of PCRE flags. You can index into this to get various compile and runtime flags.

The following are valid compile-time flags:

•	ANCHORED

•	CASELESS

•	DOLLAR_ENDONLY

•	DOTALL

•	EXTENDED

•	EXTRA

•	MULTILINE

•	NO_AUTO_CAPTURE

•	UNGREEDY

•	UTF8

The following are valid execution-time flags:

•	ANCHORED

•	NOTBOL

•	NOTEOL

•	NOTEMPTY

An example of using the flags would be:

re = rex.new ("(.+) goes (.+)", rex.flags ().CASELESS)

This would make a caseless regular expression.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:exec (Matches a regexp to a string, returning offsets)

 re:gmatch (Matches a regexp to a string, applying a function)

 re:match (Matches a regexp to a string)

 rex.new (Compiles a regular expression)

(Help topic: lua=rex.flags)


rex.new

Lua function

rex.new

Summary

Compiles a regular expression

Prototype

re = rex.new (pattern, flags)

Description

This compiles a pattern, returning a regular expression object that can be used to test regular expressions. For example:

re = rex.new ("(.+) goes (.+)")

Flags are optional. If you want to use them you can use the rex.flags () function to convert various flags into numbers.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 re:exec (Matches a regexp to a string, returning offsets)

 re:gmatch (Matches a regexp to a string, applying a function)

 re:match (Matches a regexp to a string)

 rex.flags (Returns a table of PCRE flags)

(Help topic: lua=rex.new)


select

Lua function

select

Summary

Returns items in a list

Prototype

items = select (index, ...)

Description

If index is a number, returns all items in the list from that number onwards. Otherwise index must be the string "#", in which case it returns the number of items in the list. This can be used to simulate the behaviour of the old "arg" feature in Lua 5.0, for use with variable numbers of arguments passed to a function.

function f (...)

  print (select ("#", ...))  --> 4

  print (select (2, ...))    --> 20  30  40

end -- f

f (10, 20, 30, 40)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=select)


setfenv

Lua function

setfenv

Summary

Sets a function's environment

Prototype

f = setfenv (f, env)

Description

Sets the current environment to be used by f, which can be a function, userdata, thread or stack level. Level 1 is the current function. Level 0 is the global environment of the current thread. The "env" argument is a table, which effectively becomes the "root" for the environment.

The return value is the function whose environment was changed, unless the argument was 0.

function f (v)

  test = v  -- assign to global variable test

end -- function f

local myenv = {}  -- my local environment table

setfenv (f, myenv)  -- change environment for function f

f (42)  -- call f with new environment

print (test) --> nil  (global test was not changed)

print (myenv.test)  --> 42  (test inside myenv was changed)

This can be used as a form of "sandbox", so that functions can run in an environment where they do not have access to normal global variables. For example, in the above code, you could not call "print" from inside function f, as print is not in the environment. To make it accessible you might do this:

myenv.print = print -- copy print function into environment table

A nice use of the setfenv function is to limit the damage that can be done when reading an external file.

An example is to let the user of your script provide a configuration file, that you want to read in. An example might be:

a = 42

b = "nick"

c = { "the", "quick", "brown", "fox" }

A quick way of processing that file would be to: dofile ("config.txt")

However if the "config.txt" file contained malicious code (like: os.remove "myapplication.exe") then it could have undesired side-effects. Even a simple assignment like: 'print = nil' could cause problems. The solution is to use setfenv to limit the global environment for this file, like this:

config = {} -- empty environment table

-- load the file, get a function to execute

local f = assert (loadfile ("config.txt"))

-- want to load file into the config table

setfenv (f, config)

-- load it

f ()

print (config.a)  --> 42

What this does is change the global environment for the function returned from loadfile to be the empty config table. This means that all "global" variables will be relative to config, not _G. It also means that all the standard functions (like os.remove) are not visible.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=setfenv)


setmetatable

Lua function

setmetatable

Summary

Sets the metatable for a table

Prototype

t = setmetatable (t, metatable)

Description

Sets the metatable for the nominated table. If metatable is nil, removes the metatable. If the original metatable has a "__metatable" entry an error is raised.

Returns the table.

Metatables let you add special entries that cause certain operations to behave in a different way. These operations are (each one starts with 2 underscore characters):

•	__add - the + operation

•	__sub - the - operation

•	__mul - the * operation

•	__div - the / operation

•	__pow - the ^ (exponentiation) operation

•	__unm - the unary minus operation

•	__concat - the .. (concatenate) operation

•	__eq - the == operation (a ~= b is the same as not (a == b))

•	__lt - the < operation (a > b is the same as b < a)

•	__le - the <= operation (a >= b is the same as b <= a)

•	__index - called if an antry is not in the table - prototype is: function f  (table, key)

•	__newindex - called when adding an entry to the table - prototype is: function f (table, key, value)

•	__call - called if you attempt to "call" the table

•	__gc - called after garbage collection (userdata only)

•	__mode - if it contains "k", keys are weak, if it contains "v", values are weak

•	__metatable - if present metatable cannot be changed, and this is the error message

•	__tostring - called to convert the argument to a string

•	__len - the length operator (#)

If there is no __le metamethod, Lua tries the __lt metamethod, assuming that:

a <= b  is equivalent to:  not (b < a)

Examples:

-- define adding to the table

t = { age = 42, height = 102 }

m = { __add = function (tbl, n) return t.age + n end }

setmetatable (t, m)

print (t + 1)  --> 43

-- define calling the table

t = { age = 42, height = 102 }

m = { __call = function (t) table.foreach (t, print) end }

setmetatable (t, m)

t ()  -- "call" the table (this prints each entry)

-->

height 102

age 42

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=setmetatable)


sqlite3.complete

Lua function

sqlite3.complete

Summary

Checks for a complete SQL statement

Prototype

sqlite3.complete(sql)

Description

Returns true if the string sql comprises one or more complete SQL statements and false otherwise.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=sqlite3.complete)


sqlite3.open

Lua function

sqlite3.open

Summary

Opens or creates a database

Prototype

sqlite3.open(filename)

Description

Opens (or creates if it does not exist) an SQLite database with name filename and returns its handle as userdata (the returned object should be used for all further method calls in connection with this specific database, see db:xxx methods). Example:

        myDB=sqlite3.open('MyDatabase.sqlite3')  -- open

        -- do some database calls...

        myDB:close()  -- close

In case of an error, the function returns nil, an error code and an error message.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=sqlite3.open)


sqlite3.open_memory

Lua function

sqlite3.open_memory

Summary

Opens a database in memory

Prototype

sqlite3.open_memory()

Description

Opens an SQLite database in memory and returns its handle as userdata. In case of an error, the function returns nil, an error code and an error message. (In-memory databases are volatile as they are never stored on disk.)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=sqlite3.open_memory)


sqlite3.version

Lua function

sqlite3.version

Summary

Returns the SQLite version

Prototype

sqlite3.version()

Description

Returns a string with SQLite version information, in the form 'x.y[.z]'.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=sqlite3.version)


stmt:bind

Lua function

stmt:bind

Summary

Binds a value to a parameter

Prototype

stmt:bind(n[,value])

Description

Binds value to statement parameter n. If the type of value is string or number, it is bound as text or double, respectively. If value is a boolean or nil or missing, any previous binding is removed. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind)


stmt:bind_blob

Lua function

stmt:bind_blob

Summary

Binds a blob to a parameter

Prototype

stmt:bind_blob(n,blob)

Description

Binds string blob (which can be a binary string) as a blob to statement parameter n. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind_blob)


stmt:bind_names

Lua function

stmt:bind_names

Summary

Binds values in a table to parameters

Prototype

stmt:bind_names(nametable)

Description

Binds the values in nametable to statement parameters. If the statement parameters are named (i.e., of the form ``:AAA'' or ``$AAA'') then this function looks for appropriately named fields in nametable; if the statement parameters are not named, it looks for numerical fields 1 to the number of statement parameters. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind_names)


stmt:bind_parameter_count

Lua function

stmt:bind_parameter_count

Summary

Returns the largest parameter index

Prototype

stmt:bind_parameter_count()

Description

Returns the largest statement parameter index in prepared statement stmt. When the statement parameters are of the forms ``:AAA'' or ``?'', then they are assigned sequentially increasing numbers beginning with one, so the value returned is the number of parameters. However if the same statement parameter name is used multiple times, each occurrence is given the same number, so the value returned is the number of unique statement parameter names.

If statement parameters of the form ``?NNN'' are used (where NNN is an integer) then there might be gaps in the numbering and the value returned by this interface is the index of the statement parameter with the largest index value.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind_parameter_count)


stmt:bind_parameter_name

Lua function

stmt:bind_parameter_name

Summary

Returns the name of the n'th paremeter

Prototype

stmt:bind_parameter_name(n)

Description

Returns the name of the n-th parameter in prepared statement stmt. Statement parameters of the form ``:AAA'' or ``@AAA'' or ``$VVV'' have a name which is the string ``:AAA'' or ``@AAA'' or ``$VVV''. In other words, the initial ``:'' or ``$'' or ``@'' is included as part of the name. Parameters of the form ``?'' or ``?NNN'' have no name. The first bound parameter has an index of 1. If the value n is out of range or if the n-th parameter is nameless, then nil is returned. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind_parameter_name)


stmt:bind_values

Lua function

stmt:bind_values

Summary

Binds values to parameters

Prototype

stmt:bind_values(value1,value2,...,valueN)

Description

Binds the given values to statement parameters. The function returns sqlite3.OK on success or else a numerical error code (see Numerical error and result codes).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:bind_values)


stmt:columns

Lua function

stmt:columns

Summary

Returns number of columns in the result set

Prototype

stmt:columns()

Description

Returns the number of columns in the result set returned by statement stmt or 0 if the statement does not return data (for example an UPDATE).

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:columns)


stmt:finalize

Lua function

stmt:finalize

Summary

Frees a prepared statement

Prototype

stmt:finalize()

Description

This function frees prepared statement stmt. If the statement was executed successfully, or not executed at all, then sqlite3.OK is returned. If execution of the statement failed then an error code is returned.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:finalize)


stmt:get_name

Lua function

stmt:get_name

Summary

Returns the name of a column in a result set

Prototype

stmt:get_name(n)

Description

Returns the name of column n in the result set of statement stmt. (The left-most column is number 0.)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_name)


stmt:get_named_types

Lua function

stmt:get_named_types

Summary

Returns a table of names and types for the columns in a result set

Prototype

stmt:get_named_types()

Description

Returns a table with the names and types of all columns in the result set of statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_named_types)


stmt:get_named_values

Lua function

stmt:get_named_values

Summary

Returns a table of names and values for the columns in a result set

Prototype

stmt:get_named_values()

Description

This function returns a table with names and values of all columns in the current result row of a query.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_named_values)


stmt:get_names

Lua function

stmt:get_names

Summary

Returns a table of the names of all columns in a result set

Prototype

stmt:get_names()

Description

This function returns an array with the names of all columns in the result set returned by statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_names)


stmt:get_type

Lua function

stmt:get_type

Summary

Returns the type of a column in a result set

Prototype

stmt:get_type(n)

Description

Returns the type of column n in the result set of statement stmt. (The left-most column is number 0.)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_type)


stmt:get_types

Lua function

stmt:get_types

Summary

Returns a table of the types of all columns in a result set

Prototype

stmt:get_types()

Description

This function returns an array with the types of all columns in the result set returned by statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_types)


stmt:get_unames

Lua function

stmt:get_unames

Summary

Returns a list of names of the columns in a result set

Prototype

stmt:get_unames()

Description

This function returns a list with the names of all columns in the result set returned by statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_unames)


stmt:get_utypes

Lua function

stmt:get_utypes

Summary

Returns a list of types of the columns in a result set

Prototype

stmt:get_utypes()

Description

This function returns a list with the types of all columns in the result set returned by statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_utypes)


stmt:get_uvalues

Lua function

stmt:get_uvalues

Summary

Returns a list of values of the columns in a result set

Prototype

stmt:get_uvalues()

Description

This function returns a list with the values of all columns in the current result row of a query.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_uvalues)


stmt:get_value

Lua function

stmt:get_value

Summary

Returns the value of a column in a result set

Prototype

stmt:get_value(n)

Description

Returns the value of column n in the result set of statement stmt. (The left-most column is number 0.)

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_value)


stmt:get_values

Lua function

stmt:get_values

Summary

Returns a table of the values of all columns in a result set

Prototype

stmt:get_values()

Description

This function returns an array with the values of all columns in the result set returned by statement stmt.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:get_values)


stmt:isopen

Lua function

stmt:isopen

Summary

Checks if the statement is open

Prototype

stmt:isopen()

Description

Returns true if stmt has not yet been finalized, false otherwise.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:isopen)


stmt:nrows

Lua function

stmt:nrows

Summary

Creates an iterator that returns a table of rows from a SELECT - keyed by name

Prototype

stmt:nrows()

Description

Returns an function that iterates over the names and values of the result set of statement stmt. Each iteration returns a table with the names and values for the current row. This is the prepared statement equivalent of db:nrows().

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:nrows)


stmt:reset

Lua function

stmt:reset

Summary

Resets an SQL statement, so it can be executed again

Prototype

stmt:reset()

Description

This function resets SQL statement stmt, so that it is ready to be re-executed. Any statement variables that had values bound to them using the stmt:bind*() functions retain their values.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:reset)


stmt:rows

Lua function

stmt:rows

Summary

Creates an iterator that returns a table of rows from a SELECT - numerically keyed

Prototype

stmt:rows()

Description

Returns an function that iterates over the values of the result set of statement stmt. Each iteration returns an array with the values for the current row. This is the prepared statement equivalent of db:rows().

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:step (Executes a previously-prepared SQL statement)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:rows)


stmt:step

Lua function

stmt:step

Summary

Executes a previously-prepared SQL statement

Prototype

stmt:step()

Description

This function must be called to evaluate the (next iteration of the) prepared statement stmt. It will return one of the following values:

sqlite3.BUSY: the engine was unable to acquire the locks needed. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within a explicit transaction then you should rollback the transaction before continuing.

sqlite3.DONE: the statement has finished executing successfully. stmt:step() should not be called again on this statement without first calling stmt:reset() to reset the virtual machine back to the initial state.

sqlite3.ROW: this is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. stmt:step() can be called again to retrieve the next row of data.

sqlite3.ERROR: a run-time error (such as a constraint violation) has occurred. stmt:step() should not be called again. More information may be found by calling db:errmsg(). A more specific error code (can be obtained by calling stmt:reset().

sqlite3.MISUSE: the function was called inappropriately, perhaps because the statement has already been finalized or a previous call to stmt:step() has returned sqlite3.ERROR or sqlite3.DONE.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:urows (Creates an iterator that returns the rows from a SELECT)

(Help topic: lua=stmt:step)


stmt:urows

Lua function

stmt:urows

Summary

Creates an iterator that returns the rows from a SELECT

Prototype

stmt:urows()

Description

Returns an function that iterates over the values of the result set of statement stmt. Each iteration returns the values for the current row. This is the prepared statement equivalent of db:urows().

Note: You should let the iterator finish (that is, get to the end of the selected rows) otherwise the database remains locked. So, do not "break" out of the for loop.

See Also ...

Topics

 Database (SQLite)

 Lua script extensions

 Lua SQLite (database) interface

 Lua syntax

 Scripting

 Scripting callbacks - plugins

Lua functions

 context:aggregate_count (Returns the number of calls to the aggregate step function.)

 context:get_aggregate_data (Returns the user-definable data field for callback functions.)

 context:result (This function sets the result of a callback function to res.)

 context:result_blob (This function sets the result of a callback function to the binary string in blob.)

 context:result_error (This function sets the result of a callback function to the error value in err.)

 context:result_int (This function sets the result of a callback function to the  integer value in number)

 context:result_null (This function sets the result of a callback function to nil.)

 context:result_number (This function sets the result of a callback function to the value number.)

 context:result_text (This function sets the result of a callback function to the string in str.)

 context:set_aggregate_data (Set the user-definable data field for callback functions to udata.)

 context:user_data (Returns the userdata parameter given in the call to install the callback function.)

 db:busy_handler (Sets or removes a busy handler for a database)

 db:busy_timeout (Sets a busy handler)

 db:changes (Returns number of changes by the most recent SQL statement)

 db:close (Closes a database)

 db:close_vm (Finalizes all statements that have not been explicitly finalized)

 db:create_aggregate (Creates an aggregate callback function)

 db:create_collation (Creates a collation callback)

 db:create_function (Creates a callback function)

 db:errcode (Returns the most recent result code)

 db:errmsg (Returns the most recent error message)

 db:exec (Executes SQL statements)

 db:interrupt (Interrupts any pending operation)

 db:isopen (Tests if the database is open)

 db:last_insert_rowid (Returns the key of the most recent insert into the database)

 db:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 db:prepare (Compiles an SQL statement)

 db:progress_handler (Installs a progress callback function)

 db:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 db:total_changes (Returns total number of changes)

 db:trace (Installs debug trace callback)

 db:urows (Creates an iterator that returns the rows from a SELECT)

 sqlite3.complete (Checks for a complete SQL statement)

 sqlite3.open (Opens or creates a database)

 sqlite3.open_memory (Opens a database in memory)

 sqlite3.version (Returns the SQLite version)

 stmt:bind (Binds a value to a parameter)

 stmt:bind_blob (Binds a blob to a parameter)

 stmt:bind_names (Binds values in a table to parameters)

 stmt:bind_parameter_count (Returns the largest parameter index)

 stmt:bind_parameter_name (Returns the name of the n'th paremeter)

 stmt:bind_values (Binds values to parameters)

 stmt:columns (Returns number of columns in the result set)

 stmt:finalize (Frees a prepared statement)

 stmt:get_name (Returns the name of a column in a result set)

 stmt:get_named_types (Returns a table of names and types for the columns in a result set)

 stmt:get_named_values (Returns a table of names and values for the columns in a result set)

 stmt:get_names (Returns a table of the names of all columns in a result set)

 stmt:get_type (Returns the type of a column in a result set)

 stmt:get_types (Returns a table of the types of all columns in a result set)

 stmt:get_unames (Returns a list of names of the columns in a result set)

 stmt:get_utypes (Returns a list of types of the columns in a result set)

 stmt:get_uvalues (Returns a list of values of the columns in a result set)

 stmt:get_value (Returns the value of a column in a result set)

 stmt:get_values (Returns a table of the values of all columns in a result set)

 stmt:isopen (Checks if the statement is open)

 stmt:nrows (Creates an iterator that returns a table of rows from a SELECT - keyed by name)

 stmt:reset (Resets an SQL statement, so it can be executed again)

 stmt:rows (Creates an iterator that returns a table of rows from a SELECT - numerically keyed)

 stmt:step (Executes a previously-prepared SQL statement)

(Help topic: lua=stmt:urows)


string literals

Literal strings (constants) are delimited by single or double quotes. Square brackets can also be used, as described below.

The same quote that starts the string ends it, allowing you to use the other quote inside the string, eg.

a = "Nick's cat"

b = 'Nick says "hello" to you'

You can also use certain "escape" sequences to imbed special characters:

\a	bell (0x07)

\b	backspace  (0x08)

\f	form feed (0x0C)

\n	newline  (0x0A)

\r	carriage return (0x0D)

\t	horizontal tab (0x09)

\v	vertical tab (0x0B)

\\	backslash

\"	double quote

\'	single quote

\[	left square bracket

\]	right square bracket

You can also imbed other codes by using \ddd where ddd is up to 3 decimal digits. For example:

a = "\027"  -- the "escape" character (hex 0x1B)

Be cautious if you do not use exactly three digits, because then another digit following the code might be considered to be part of it.

You can also use square brackets to make multiple-line strings, or strings with both sorts of quotes inside them. For example:

a = [[

Here you will experience your first full combat against MOBILES, also known

as MOBS. Mobile is the name used for monsters and the like in the game.

All exits, except down, lead to a CAGE mob. Some of these cage mobs may be

aggressive and will attack you upon entering their room. As you kill them,

you will gain experience, as well as academy equipment and gold.

]]

This sort of literal string ignores escape sequences. It also discards a newline if the first character is a newline (as in the example above).

If you might have two brackets inside the string you can use "=" signs to make strings which only match the same number of "=" signs at the end, for example:

a = [====[

Here you will experience your first full combat against MOBILES, also known

as MOBS. Mobile is the name used for monsters and the like in the game.

All exits, except down, lead to a CAGE mob. Some of these cage mobs may be

aggressive and will attack you upon entering their room. As you kill them,

you will gain experience, as well as academy equipment and gold.

]====]

Another way of doing multiple-line strings is to put a backslash at the end of the line, eg.

a = "Here you will experience your first full combat against MOBILES, also known \

as MOBS. Mobile is the name used for monsters and the like in the game. \

All exits, except down, lead to a CAGE mob. Some of these cage mobs may be \

aggressive and will attack you upon entering their room. As you kill them, \

you will gain experience, as well as academy equipment and gold."

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 tables (Table data types)

 while (Loop with test at start)

(Help topic: lua=string literals)


string.byte

Lua function

string.byte

Summary

Converts a character into its ASCII (decimal) equivalent

Prototype

code = string.byte (s, n)

Description

Returns the ASCII code for the nth character of the string s. The inverse operation is carried out by string.char.

Default for n is 1.

print (string.byte ("ABC")) --> 65 (A is 65 in ASCII)

print (string.byte ("ABC", 2)) --> 66 (B is 66)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.byte)


string.char

Lua function

string.char

Summary

Converts ASCII codes into their equivalent characters

Prototype

s = string.char (n1, n2, n3, ...)

Description

Receives 0 or more numbers and converts them to the corresponding characters. The inverse operation is carried out by string.byte.

print (string.char (65, 66)) --> AB

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.char)


string.dump

Lua function

string.dump

Summary

Converts a function into binary

Prototype

s = string.dump (f)

Description

Converts a function f into binary representation, which can be subsequently processed by loadstring to retrieve the function. The function must be a Lua function without upvalues.

function f () print "hello, world" end

s = string.dump (f)

assert (loadstring (s)) () --> hello, world

Note: this does not currently work if you are using the LuaJIT DLL instead of the one that ships with the normal MUSHclient download. One way of testing for the presence of LuaJIT is to run this:

print (jit.version) --> LuaJIT 2.0.0-beta7

If LuaJIT is not installed you would see something like:

Error: attempt to index global 'jit' (a nil value)

Further note: Using string.dump is not recommended. Apart from the issues with LuaJIT it may not be portable across Lua releases or different operating system platforms.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.dump)


string.find

Lua function

string.find

Summary

Searches a string for a pattern

Prototype

st, en, cap1, cap2, cap3 = string.find (str, pattern, index, plain)

Description

Find the first match of the regular expression "pattern" in "str", starting at position "index".

The starting position (index) is optional, and defaults to 1 (the start of the string).

If found, returns the start and end position, and any captures as additional results.

If not found, returns nil.

If "plain" is true, the search string is plain text, not a regular expression. (The "plain" argument is optional, and defaults to false).

Also see:

•	string.match which operates in a similar way, but does not return the start and end positions

•	string.gmatch which iterates over a string, allowing you to take action on each match (eg. on each word)

•	string.gsub which lets you make replacements on matching elements (for example, replace one word with another, or make certain things all upper-case)

Patterns

The standard patterns (character classes) you can search for are:

 . --- (a dot) represents all characters.

%a --- all letters.

%c --- all control characters.

%d --- all digits.

%l --- all lowercase letters.

%p --- all punctuation characters.

%s --- all space characters.

%u --- all uppercase letters.

%w --- all alphanumeric characters.

%x --- all hexadecimal digits.

%z --- the character with hex representation 0x00 (null).

%% --- a single '%' character.

%1 --- captured pattern 1.

%2 --- captured pattern 2 (and so on).

%f[s]  transition from not in set 's' to in set 's'.

%b()   balanced nested pair ( ... ( ... ) ... )

Important! - the uppercase versions of the above represent the complement of the class. eg. %U represents everything except uppercase letters, %D represents everything except digits.

Also important! If you are using string.find (or string.match etc.) in MUSHclient, and inside "send to script" in a trigger or alias, then the % sign has special meaning there (it is used to identify wildcards, for example, %1 is wildcard 1). Thus the % signs in string.find need to be doubled or they won't work properly (so use %%d instead of %d in "send to script"). This does not apply if you are scripting in a script file, because the expansion of wildcards does not apply there.

Magic characters

There are some "magic characters" (such as %) that have special meanings. These are:

^ $ ( ) % . [ ] * + - ?

If you want to use those in a pattern (as themselves) you must precede them by a % symbol.

eg. %% would match a single %  (also see note above about "send to script")

In practice, it is safe to put % in front of any non-alphanumeric character. If in doubt, put a % in front of a special character.

Quotes and backslashes

The arguments to string.find (and string.match, etc.) are just normal Lua strings. Thus, to put a backslash or quote inside such a string you still need to "escape" it with a backslash in the usual way.

eg. string.find (str, "\\")  -- find a single backslash

Sets

You can build your own pattern classes (sets) by using square brackets, eg.

[abc] ---> matches a, b or c

[a-z] ---> matches lowercase letters (same as %l)

[^abc] ---> matches anything except a, b or c

[%a%d] ---> matches all letters and digits

[%a%d_] ---> matches all letters, digits and underscore

[%[%]] ---> matches square brackets (had to escape them with %)

You can use pattern classes in the form %x in the set. If you use other characters (like periods and brackets, etc.) they are simply themselves.

You can specify a range of character inside a set by using simple characters (not pattern classes like %a) separated by a hyphen. For example, [A-Z] or [0-9]. These can be combined with other things. For example [A-Z0-9] or [A-Z,.].

The end-points of a range must be given in ascending order. That is, [A-Z] would match upper-case letters, but [Z-A] would not match anything.

A hyphen at the start or end of a set is itself (matches a hyphen).

You can negate a set by starting it with a "^" symbol, thus [^0-9] is everything except the digits 0 to 9. The negation applies to the whole set, so [^%a%d] would match anything except letters or digits. In anywhere except the first position of a set, the "^" symbol is simply itself.

Inside a set (that is a sequence delimited by square brackets) the only "magic" characters are:

] ---> to end the set, unless preceded by %

% ---> to introduce a character class (like %a), or magic character (like "]")

^ ---> in the first position only, to negate the set (eg. [^A-Z)

- ---> between two characters, to specify a range (eg. [A-F])

Thus, inside a set, characters like "." and "?" are just themselves.

Repetition

The repetition characters, which can follow a character, class or set, are:

+  ---> 1 or more repetitions (greedy)

*  ---> 0 or more repetitions (greedy)

-  ---> 0 or more repetitions (non greedy)

?  ---> 0 or 1 repetition only

A "greedy" match will match on as many characters as possible, a non-greedy one will match on as few as possible.

Anchor to start and/or end of string

The standard "anchor" characters apply:

^  ---> anchor to start of subject string (must be the very first character)

$  ---> anchor to end of subject string   (must be the very last character)

For example:

^You see     ---> string must start with "You see"

experience$  ---> string must end with "experience"

^Tick$       ---> string must be exactly "Tick" with no other characters

Captures

You can also use round brackets to specify "captures":

You see (.*) here

Here, whatever matches (.*) becomes the first capture.

You can also refer to matched substrings (captures) later on in an expression:

print (string.find ("You see dogs and dogs", "You see (.*) and %1")) --> 1 21 dogs

print (string.find ("You see dogs and cats", "You see (.*) and %1")) --> nil

This example shows how you can look for a repetition of a word matched earlier, whatever that word was ("dogs" in this case).

As a special case, an empty capture string returns as the captured pattern, the position of itself in the string. eg.

print (string.find ("You see dogs and cats", "You .* ()dogs .*")) --> 1 21 9

What this is saying is that the word "dogs" starts at column 9.

There is a limit of 32 captures that can be returned.

Balanced sequences

Finally you can look for nested "balanced" things (such as parentheses) by using %b, like this:

print (string.find ("I see a (big fish (swimming) in the pond) here",

       "%b()"))  --> 9 41

After %b you put 2 characters, which indicate the start and end of the balanced pair. If it finds a nested version it keeps processing until we are back at the top level. In this case the matching string was "(big fish (swimming) in the pond)".

Frontier patterns

A "frontier" (or boundary) pattern is used to assert a transition from one set of characters to another (eg. non-letters to letters, or non-digits to digits). This can be useful to detect words, such as "log" but omit "blog" or "logging".

A frontier is specified as %f[set] and matches on a transition from not-in-set to in-set. For example, to match "log" on its own:

print (string.find ("There is a log here", "%f[%a]log%f[%A]"))   --> 12 14

print (string.find ("There is a blog here", "%f[%a]log%f[%A]"))  --> nil

print (string.find ("There is logging here", "%f[%a]log%f[%A]")) --> nil

The first frontier ("%f[%a]") matches on the transition from not-letters to letters. The second frontier ("%f[%A]") matches on letters to not-letters. Effectively this gives you a word boundary match.

Examples

print (string.find ("the quick brown fox", "quick")) --> 5 9

print (string.find ("the quick brown fox", "(%a+)")) --> 1 3 the

print (string.find ("the quick brown fox", "(%a+)", 10)) --> 11 15 brown

print (string.find ("the quick brown fox", "fruit")) --> nil

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.find)


string.format

Lua function

string.format

Summary

Formats a string

Prototype

s = string.format (fstr, v1, v2, v3, ...)

Description

Formats the supplied values (v1, v2 etc.) using format string 'fstr', similar to the C function printf.

It is an error to supply too few variables for the format string.

The format string comprises literal text, and directives starting with %. Each directive controls the format of the next argument. Directives can include flags, width and precision controls. To literally incorporate "%" in the output you need to put "%%" in the format string.

For example:

print (string.format ("To wield the %s you need to be level %i", "sword", 10))

Prints:

To wield the sword you need to be level 10

In this example the values "sword" and "10" are substituted where the %s and %i appear in the format string.

Important! If you are using string.format in MUSHclient, and inside "send to script" in a trigger or alias, then the % sign has special meaning there (it is used to identify wildcards, such as %1 is wildcard 1). Thus the % signs in string.format need to be doubled or they won't work properly.

For example:

print (string.format ("To wield the %%s you need to be level %%i", "sword", 10))

This does not apply if you are using a separate script file.

Directives can be:

•	%c - convert a number to a single character (like string.char)

string.format ("%c", 65) --> A

•	%d and %i - output as an integer number

string.format ("%i", 123.456) --> 123

•	%o - convert to octal

string.format ("%o", 16) --> 20

•	%u - convert to an unsigned number

Negative numbers will be converted to 4294967296 (2^32) minus the number.

string.format ("%u", 1234.566) --> 1234

string.format ("%u", -1234)    --> 4294966062

•	%x - hex (lower-case)

string.format ("%x", 86543) --> 1520f

•	%X - hex (upper-case)

string.format ("%X", 86543)--> 1520F

•	%e - scientific notation, "e" in lower case:

string.format ("%e", 15) --> 1.500000e+001

•	%E - scientific notation, "E" in upper case:

string.format ("%E", 15) --> 1.500000E+001

•	%f - floating point, default to 6 decimal places:

string.format ("%f", 15.656e4) --> 156560.000000

•	%g - Signed value printed in %f or %e format, whichever is more compact for the given value. To make it compact, only the required number of decimal places (if any) are shown.

string.format ("%g", 15.656) --> 15.656

string.format ("%g", 1)      --> 1

string.format ("%g", 1.2)    --> 1.2

•	%G - Same as %g except that an upper-case E is used where appropriate.

string.format ("%G", 15.656e42) --> 1.5656E+043

•	%q - formats a string in such a way Lua can read it back in (eg. as Lua source).

Basically this means:

•	It puts a backslash in front of the double quote character (hex 22), backslash itself (hex 5C), and newline (hex 0A).

•	The nul character (hex 00) becomes \000

•	Carriage return (hex 0D) becomes \r

The string itself is surrounded by double quotes.

For example:

print (string.format ("%q", 'a cat called "Puss"')) --> "a cat called \"Puss\""

•	%s - output a string (or something that can be converted to a string, such as a number).

•	%% - output a single % character

You can optionally supply 'flags width.precision' arguments before the letter.

Flags can be:

•	- : left align result inside field

•	+ : always prefix with a sign, using + if field positive

•	0 : left-fill with zeroes rather than spaces

•	(space) : If positive, put a space where the + would have been

•	# : Changes the behaviour of various formats, as follows:

For octal conversion (o), prefixes the number with 0 - if necessary.

For hex conversion (x), prefixes the number with 0x

For hex conversion (X), prefixes the number with 0X

For e, E and f formats, always show the decimal point.

For g and G format, always show the decimal point, and do not truncate trailing zeroes.

The option to 'always show the decimal point' would only apply if you had the precision set to 0.

Width is the width of the returned field. If the converted number/string is wider than the width it is not truncated. Thus, this is effectively the minimum width. The maximum width you can specify is 99.

Decimal places are counted in the width, so something like %10.4f will actually have 5 digits before the decimal place. (5 before, plus 1 for the decimal point, plus 4 after adds up to 10).

You cannot use "*" as the width (as you can for printf). If you want variable-size strings you can simulate that by modifying the format string on-the-fly.

eg. instead of %*g, use "%" .. width .. "g"

Precision is the number of decimal places to show for floating-point numbers. The maximum precision you can specify is 99.

For strings the length of the source string is truncated to the precision size.

If the precision is omitted it defaults to 6 decimal places for 'e', 'E' and 'f' format types. If decimal places are omitted by the specified precision, the result is rounded.

Examples:

string.format ("%15.1f", 15.656)   --> '           15.7'

string.format ("%15.8f", 15.656)   --> '    15.65600000'

string.format ("%-15.1f", 15.656)  --> '15.7           '

string.format ("%015.1f", 15.656)  --> '0000000000015.7'

string.format ("%+015.1f", 15.656) --> '+000000000015.7

string.format ("%5s", "hi")          --> '   hi'

string.format ("%-5s", "hi")         --> 'hi   '

string.format ("%.4s", "Nick Gammon")--> 'Nick'  (truncation)

string.format ("%9.4s", "John Smith")--> '     John'

string.format ("%.f", 4.4)           --> '4'  (precision of zero)

string.format ("%.f", 4.5)           --> '5'  (rounding)

string.format ("%#.f", 4.4)          --> '4.' (decimal place forced)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.format)


string.gfind

Lua function

string.gfind

Summary

Iterate over a string (obsolete in Lua 5.1)

Prototype

it = string.gfind (str, pattern)

Description

This function is now called string.gmatch. Calling string.gfind raises an error.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.gfind)


string.gmatch

Lua function

string.gmatch

Summary

Iterate over a string

Prototype

it = string.gmatch (str, pattern)

Description

Returns an iterator function for returning the next capture from a pattern over a string. If there is no capture, the whole match is produced.

See string.find for an explanation of regular expressions.

for w in string.gmatch ("nick takes a stroll", "%a+") do

  print (w)

end -- for

-->

nick

takes

a

stroll

For this function, a '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.gmatch)


string.gsub

Lua function

string.gsub

Summary

Substitute strings inside another string

Prototype

s, n = string.gsub (str, pattern, replacement, n)

Description

Returns a copy of str with matches to 'pattern' replaced by 'replacement', for a maximum of n times.

As a second result it returns the number of matches made.

'replacement' can be a string in which case it simply replaces the matching pattern. However %1 through to %9 in the replacement pattern can refer to captured strings in the source pattern. %% becomes %. Also, %0 in the replacement pattern refers to the entire matching string.

If 'replacement' is a function it is called for each match with the matching string as an argument. It should return a string which is the string to replace it with. If it returns nil the original string is retained.

If 'replacement' is a table then the matching string is looked up in the table for each match, and if found, the replacement is substituted.

See string.find for an explanation of regular expressions.

string.gsub ("nick eats fish", "fish", "chips") --> nick eats chips

-- example of using a function as the replacement

replacements = {

   ["nice"] = "windy",

   ["walk"] = "stroll",

   }

s = "a nice long walk"

result = string.gsub (s, "%a+",

  function (str)

  return replacements [str]

  end

  )

print (result) --> a windy long stroll

-- An alternative way of doing a table replacement using the above table:

result = string.gsub (s, "%a+", replacements)

print (result) --> a windy long stroll

-- You can call inbuilt functions too:

s = "a nice long walk"

result = string.gsub (s, "%f[%a]%a%a", string.upper)

print (result) --> a NIce LOng WAlk

If you need to search for something that is not a regular expression, you need to "fix up" the search string first. This should do it:

search = string.gsub (search, "[%%%]%^%-$().[*+?]", "%%%1")

The code above fixes all of the special characters recognized in a regular expression by preceding them with a percent symbol.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.gsub)


string.len

Lua function

string.len

Summary

Return the length of a string

Prototype

n = string.len (str)

Description

Returns the length of the string, including any imbedded zero (0x00) bytes.

string.len ("hi there") --> 8

You can also use #string to find its length.

#"hi there" --> 8

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.len)


string.lower

Lua function

string.lower

Summary

Converts a string to lower-case

Prototype

s = string.lower (str)

Description

Returns the string converted to lower-case.

string.lower ("ABCdef") --> abcdef

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.lower)


string.match

Lua function

string.match

Summary

Searches a string for a pattern

Prototype

cap1, cap2, cap3 = string.match (str, pattern, index)

Description

Find the first match of the regular expression "pattern" in "str", starting at position "index".

The starting position (index) is optional, and defaults to 1 (the start of the string).

If found, returns any captures in the pattern. If no captures were specified the entire matching string is returned.

If not found, returns nil.

This is similar to string.find, except that the starting and ending index are not returned.

print (string.match ("You see dogs and cats", "s..")) --> see

See string.find for an explanation of regular expressions.

Note: string.match does not have the option for a "plain" search. If you want to do a search without regular expressions, use string.find.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.match)


string.rep

Lua function

string.rep

Summary

Returns repeated copies of a string

Prototype

s = string.rep (str, n)

Description

Returns a string which is n copies of the source string concatenated together.

string.rep ("moo", 4) --> moomoomoomoo

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.rep)


string.reverse

Lua function

string.reverse

Summary

Reverses the order of characters in a string

Prototype

s = string.reverse (str)

Description

Returns a string that is the string str reversed.

string.reverse ("nickgammon") --> nommagkcin

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.sub (Returns a substring of a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.reverse)


string.sub

Lua function

string.sub

Summary

Returns a substring of a string

Prototype

s = string.sub (str, start, end)

Description

Returns a substring of the string, starting at index 'start' and ending at index 'end'. Both may be negative to indicate counting from the right. The end point is optional and defaults to -1, which is the entire rest of the string.

string.sub ("ABCDEF", 2, 3)  --> BC

string.sub ("ABCDEF", 3)     --> CDEF

string.sub ("ABCDEF", -1)    --> F

See also utils.utf8sub for doing the identical operation with UTF-8 strings.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.upper (Converts a string to upper-case)

(Help topic: lua=string.sub)


string.upper

Lua function

string.upper

Summary

Converts a string to upper-case

Prototype

s = string.upper (str)

Description

Returns the string converted to upper-case.

string.upper ("ABCdef") --> ABCDEF

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Regular Expressions

 Scripting

 Scripting callbacks - plugins

Lua functions

 string.byte (Converts a character into its ASCII (decimal) equivalent)

 string.char (Converts ASCII codes into their equivalent characters)

 string.dump (Converts a function into binary)

 string.find (Searches a string for a pattern)

 string.format (Formats a string)

 string.gfind (Iterate over a string (obsolete in Lua 5.1))

 string.gmatch (Iterate over a string)

 string.gsub (Substitute strings inside another string)

 string.len (Return the length of a string)

 string.lower (Converts a string to lower-case)

 string.match (Searches a string for a pattern)

 string.rep (Returns repeated copies of a string)

 string.reverse (Reverses the order of characters in a string)

 string.sub (Returns a substring of a string)

(Help topic: lua=string.upper)


table.concat

Lua function

table.concat

Summary

Concatenates table items together into a string

Prototype

s = table.concat (t, sep, start, end)

Description

Returns the (numeric) entries in the table t, concatenated together with "sep" as the separator, starting at index 'start' and ending at index 'end'. The entries are returned as a single string variable. Contrast this to the "unpack" function which returns a table as individual variables.

Start defaults to 1 and end the table size.

Sep defaults to an empty string.

t = { "the", "quick", "brown", "fox" }

print (table.concat (t, ';')) --> the;quick;brown;fox

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.concat)


table.foreach

Lua function

table.foreach

Summary

Applies a function to each item in a table

Prototype

val = table.foreach (t, f)

Description

Executes f for each element in table t.

Function f is called with the arguments (key, value).

If f returns a non-nil value the loop is broken, and this value is returned as the result from table.foreach. Effectively this could be used to find an element inside a table matching a certain condition.

t = { "the", "quick", "brown", "fox", name = "Nick" }

table.foreach (t, print)

 -->

1 the

2 quick

3 brown

4 fox

name Nick

Warning the use of table.foreach is deprecated. This means it may not be available in future versions of Lua. You are recommended to rewrite such uses by using the 'pairs' function. For example:

for k, v in pairs (t) do

  f (k, v)

end

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.foreach)


table.foreachi

Lua function

table.foreachi

Summary

Applies a function to each item in a numerically-keyed table

Prototype

val = table.foreachi (t, f)

Description

Executes f for each element in table t.

Function f is called with the arguments (key, value).

If f returns a non-nil value the loop is broken, and this value is returned as the result from table.foreach. Effectively this could be used to find an element inside a table matching a certain condition.

Similar to table.foreach, except that only numeric keys in the range 1 to n are processed.

t = { "the", "quick", "brown", "fox", name = 'Nick' }

table.foreachi (t, print)

 -->

1 the

2 quick

3 brown

4 fox

In this example the entry for "name = 'Nick'" was not returned because it did not have a numeric key.

Warning the use of table.foreachi is deprecated. This means it may not be available in future versions of Lua. You are recommended to rewrite such uses by using the 'ipairs' function. For example:

for k, v in ipairs (t) do

  f (k, v)

end

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.foreachi)


table.getn

Lua function

table.getn

Summary

Returns the size of a numerically-keyed table

Prototype

n = table.getn (t)

Description

Returns the size of the table using the rules described at the start of this page.

A table's size (which is only relevant for "numeric" indexed tables) is one less than the first integer index with a nil value. If the table has "holes" in it - that is, numeric keys with gaps in the sequence - then the table size is not guaranteed to be the the last gap. Lua does a binary search to try to find a gap, it does not necessarily find the first or last one.

table.getn { "the", "quick", "brown", "fox", name = "Nick" } --> 4

Note that the length here is 4 and not 5, because the non-numeric entry (name = "Nick") is not considered to be part of the table's "length".

You can also use #t to find the length of a table.

# { "the", "quick", "brown", "fox", name = "Nick" } --> 4

Contrast to table.maxn which finds the highest key by a linear scan (and is therefore slower).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.getn)


table.insert

Lua function

table.insert

Summary

Inserts a new item into a numerically-keyed table

Prototype

table.insert (t, pos, value)

Description

Inserts the value at (optional) position 'pos', renumbering existing elements if necessary to make room. Thus the new element becomes the one with index 'pos'.

If called with 2 arguments, the value is inserted at n+1, that is, the end of the table.

t = { "the", "quick", "brown", "fox" }

table.insert (t, 2, "very") -- new element 2

table.insert (t, "jumped")  -- add to end of table

table.foreachi (t, print)

 -->

1 the

2 very

3 quick

4 brown

5 fox

6 jumped

The Lua authors recommend using the idiom "#t + 1" to insert to the end of a table nowadays. For example:

t = {}

t [#t + 1] = "hello, "

t [#t + 1] = "world"

Note that for other keys (eg. strings) you simply assign to the table item to insert it. For example:

t = {}

t.foo = "bar"    -- insert key "foo"

t ["Nick Gammon"] = 42  -- insert key "Nick Gammon"

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.insert)


table.maxn

Lua function

table.maxn

Summary

Returns the highest numeric key in the table

Prototype

n = table.maxn (t)

Description

Returns the highest numeric key in the table, by examining each entry in the entire table. This will necessarily be slower than doing table.getn, but would be needed if the keys have gaps in the sequence.

If the table does not have gaps in the keys, it is faster to use table.getn.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.maxn)


table.remove

Lua function

table.remove

Summary

Removes an item from a numerically-keyed table

Prototype

val = table.remove (t, pos)

Description

Removes the element at position 'pos' from the table, returning the value of the removed element.

If 'pos' is omitted it defaults to the end of the table (n), thus removing the last element.

t = { "the", "quick", "brown", "fox" }

print (table.remove (t, 3))

table.foreachi (t, print)

 -->

brown

1 the

2 quick

3 fox

The Lua authors recommend using this method for removing from the end of a table nowadays:

t [#t] = nil  -- remove last entry

Note that for other keys (eg. strings) you simply assign nil to the element to remove it. For example:

t = {}

t.foo = "bar"  -- add item

t.foo = nil    -- remove item

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.setn (Sets the size of a table (obsolete))

 table.sort (Sorts a table)

(Help topic: lua=table.remove)


table.setn

Lua function

table.setn

Summary

Sets the size of a table (obsolete)

Prototype

table.setn (t, n)

Description

This has been removed from Lua 5.1. Attempting to call it will raise an error. The length of a table can not be set, it is implied by the highest numeric key, providing there are no gaps in the sequence of numeric keys.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.sort (Sorts a table)

(Help topic: lua=table.setn)


table.sort

Lua function

table.sort

Summary

Sorts a table

Prototype

table.sort (t, f)

Description

Sorts the table using the supplied function f as the comparison function for each element.

Function f should return true if the first element is < the second element. If the function omitted it defaults to the operator <.

Sorting is not stable, that is, the sequence of equal keys is not necessarily preserved.

t = { "the", "quick", "brown", "fox" }

table.sort (t)

table.foreachi (t, print)

 -->

1 brown

2 fox

3 quick

4 the

Sorting is really only relevant for numerically keyed tables. If you want to sort the keys for other types of tables you need to make a copy of the keys and sort that, like this:

t = { str = 42, dex = 10, wis = 100 }

ts = {} -- table to hold the keys

table.foreach (t, function (k, v) table.insert (ts, k) end )

table.sort (ts) -- sort keys

table.foreachi (ts, print) -- print sorted keys

 -->

1 dex

2 str

3 wis

Here is an example of a custom sort function. This is needed here because we are sorting tables, which do not have a natural "less than" operator:

t = {

    { str = 42, dex = 10, wis = 100 },

    { str = 18, dex = 30, wis = 5 }

    }

table.sort (t, function (k1, k2) return k1.str < k2.str end )

table.foreachi (t, function (k, v) table.foreach (v, print) end )

 -->

str 18

dex 30

wis 5

str 42

dex 10

wis 100

We can see from the results that the two tables were sorted into "str" order.

An alternative approach to supplying a comparison function for the sort would be to set up a metatable for the individual table items (not the container table) which specifies a __lt (less than) operator. Here is an example:

t = {

    { str = 42, dex = 10, wis = 100 },

    { str = 18, dex = 30, wis = 5 }

    }

mt =  { __lt = function (k1, k2) return k1.wis < k2.wis end }

-- apply metatable to all tables inside our table

for _, v in ipairs (t) do

  setmetatable (v, mt)

end -- for

table.sort (t)

table.foreachi (t, function (k, v) table.foreach (v, print) end )

 -->

str 18

dex 30

wis 5

str 42

dex 10

wis 100

In this case I have made a  metatable "mt" which is then applied to each table item. It compares the "wis" field in this case. With this in place the sort can be called without a helper function. Of course, for speed purposes you would do this once (perhaps when creating the individual table entries) rather than every time you wanted to sort it.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 table.concat (Concatenates table items together into a string)

 table.foreach (Applies a function to each item in a table)

 table.foreachi (Applies a function to each item in a numerically-keyed table)

 table.getn (Returns the size of a numerically-keyed table)

 table.insert (Inserts a new item into a numerically-keyed table)

 table.maxn (Returns the highest numeric key in the table)

 table.remove (Removes an item from a numerically-keyed table)

 table.setn (Sets the size of a table (obsolete))

(Help topic: lua=table.sort)


tables

Tables implement associative arrays. That is, arrays of key/value pairs.

The keys and values can be any type, except nil.

The only way to create a table is by using a "table constructor" like this:

t = {}

The table constructor can also add initial key/value pairs to the table, eg.

foods = {

   fish  = 10,

   chips = 11,

   cake  = 12

   }

You can add elements later or in the constructor. Ultimately either method gives the same end result.

Once you have a table you can get at the values in it by "indexing" into the table. One way is this:

print ( foods ["fish"] )  --> 10

Or in the case of string keys, where the key follows the rules for identifiers, you can use this shortcut:

print ( foods.fish )  --> 10

Tables are anonymous, they don't have to be stored in any variable, or one table might be stored (by reference) in many variables. For example:

print ( { a = 42 } )  --> table: 01D75990

That table existed even though it was not assigned to a variable.

x = { a = 42 }

y = x

In this example both x and y refer to the same table. The assignment did not make a copy of the table, it made a copy of the reference to the table.

Table constructors in the general form provide the key in brackets:

foods = {

   ["fish"]  = 10,

   ["chips"] = 11,

   ["cake"]  = 12

   }

This is equivalent to the earlier example.

For other data types you must use brackets for the key, eg.

squares = {

   [2] = 4,

   [3] = 9,

   [4] = 16,

   }

Both the keys and values can be any type except nil, so a table can contain nested tables, or boolean values, for example.

Lua can also automatically assign keys starting at one, like this:

words = {

  "every",    -- assigned key 1

  "good",     -- assigned key 2

  "boy",      -- assigned key 3

  "deserves", -- assigned key 4

  "fruit",    -- assigned key 5

   }

Elements in tables are separated by a comma or semicolon. It is acceptable to have a trailing comma or semicolon, to assist in machine-generated tables.

Note that there is a difference between the key "10" (a string) and the key 10 (a number).

By convention, in Lua tables start with one (not zero as in C). The Lua libraries are designed around this convention. You can "manually" put an element at position 0 if you need to:

t = {

   [0] = "zero",

   [1] = "one",

   [2] = "two,

   }

You can add elements to a table at any time, eg.

words [6] = "bread"  -- add (or replace) the key/value pair

You can remove elements by assigning nil as their value, eg.

words [2] = nil  -- delete entry for key 2

You can also use table.insert to add numerically keyed items to a table. This will shuffle existing keys upwards to make room if required.

Likewise, you can use table.remove to remove numerically keyed items from a table. This will shuffle existing keys downwards where required.

You do not specifically delete tables. Once there are no references to the table the garbage-collector will delete it. One way of encouraging that to happen is to assign nil to any variables which refer to the table:

words = nil  -- finished with table

You can see if a table is empty or not by using the next function:

print (next (words))  --> prints nil if table is empty

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 while (Loop with test at start)

(Help topic: lua=tables)


tonumber

Lua function

tonumber

Summary

Converts a string (of the given base) to a number

Prototype

n = tonumber (n, base)

Description

Converts n to a number using the optional base (default 10). Base can be from 2 to 36. For bases > 10 the letters a-z (not case sensitive) represent the digits. (eg. F is 15).

For decimal numbers you can supply fractions and exponents. Others should be unsigned.

Returns nil if the number cannot be converted.

print (tonumber ("100100", 2)) --> 36

print (tonumber ("1e5")) --> 100000

print (tonumber ("1EF", 16)) --> 495

You can use tonumber as a quick check if a variable contains something convertable to a number.

print (tonumber ("abc")) --> nil

print (tonumber ("-43")) --> -43

print (tonumber (-43))   --> -43

To see if the variable actually is already a number type, use the "type" function:

print (type ("-43")) --> string

print (type (-43))   --> number

See also bit.tonumber which will handle larger numbers.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=tonumber)


tostring

Lua function

tostring

Summary

Converts its argument to a string

Prototype

s = tostring (a)

Description

Converts its argument to a string in a reasonable format. If a __tostring metatable field is found, that is used for the conversion.

print (tostring (print)) --> function: 0205A980

print (tostring (_G)) --> table: 02072780

print (tostring (1.23e10)) --> 12300000000

-- use __tostring to print a table

t = { age = 42, height = 102 }

setmetatable (t,

  {

  __tostring = function (t)

    return "person of age " .. t.age

    end -- __tostring

  }

 )

print (t) --> person of age 42

Also see bit.tostring which will convert a number to a string of any base in the range 2 to 36.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=tostring)


type

Lua function

type

Summary

Returns the type of a variable

Prototype

s = type (v)

Description

Returns a string, which is the type of the supplied variable:

•	nil

•	number

•	string

•	boolean

•	table

•	function

•	thread

•	userdata

print (type (42)) --> number

print (type ("42")) --> string

print (type (string)) --> table

print (type (tonumber)) --> function

Note that if its argument is nil, it returns "nil" - that is the string containing the word "nil".

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 unpack (Unpacks a table into individual items)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=type)


unpack

Lua function

unpack

Summary

Unpacks a table into individual items

Prototype

t1, t2, ... = unpack (t)

Description

Returns all elements from the given list (table) as individual values. This is equivalent to:

return t [1], t [2], t [3] ..., t [n]

t = { "the", "quick", "brown" }

print (unpack (t)) --> the quick brown

An example of using unpack is the case of a variable number of arguments to a function, where you want to pass those to another function.

For example, to make an error function that takes a formatted string:

function ferror (fmt, ...)

  error (string.format (fmt, unpack (arg)), 2)

end -- ferror

However in Lua 5.1 this is more simply written as:

function ferror (fmt, ...)

  error (string.format (fmt, ...), 2)

end -- ferror

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 xpcall (Calls a function with a custom error handler)

(Help topic: lua=unpack)


utils.activatenotepad

Lua function

utils.activatenotepad

Summary

Actvitates the specified notepad window

Prototype

utils.activatenotepad (title)

Description

Activates the nominated notepad window, which does not belong to any world.

This is intended to be used for debugging or displaying information (eg. during development of localization scripts) in a notepad window, which is not related to any particular world.

eg.

utils.activatenotepad ("Debugging")

Returns true if successful, false if unsuccessful. (It would be false if the notepad did not exist).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.activatenotepad)


utils.appendtonotepad

Lua function

utils.appendtonotepad

Summary

Appends text to the specified notepad window

Prototype

utils.appendtonotepad (title, message, replace)

Description

Appends text to the nominated notepad window, which does not belong to any world.

This is intended to be used for debugging or displaying information (eg. during development of localization scripts) in a notepad window, which is not related to any particular world.

eg.

utils.appendtonotepad ("Debugging", "Loaded 10 files", false)

Returns true if successful, false if unsuccessful.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.appendtonotepad)


utils.base64decode

Lua function

utils.base64decode

Summary

Decode a string which was base-64 encoded

Prototype

s = utils.base64decode (s)

Description

Decodes the string 's' from base64 encoding to plain text. The decoded string may contain the null byte (ie. hex 00). Otherwise, this is the same behaviour as the world.Base64Decode function. Bytes that are invalid are skipped (eg. spaces, newlines, other junk).

eg.

print (utils.base64decode ("TmljayBHYW1tb24=")) --> Nick Gammon

If the source string is not a multiple of 4 bytes then the last few bytes of the decoded string will be lost (because decoding is done in batches of 4 input bytes to 3 output bytes).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.base64decode)


utils.base64encode

Lua function

utils.base64encode

Summary

Encode a string with base-64 encoding

Prototype

s = utils.base64encode (s [, linebreaks])

Description

Encodes the string 's' in base64 encoding (suitable for emails etc.). If 'linebreaks' is true, there will be a carriage return/linefeed every 76 characters. The string 's' may contain the null byte (ie. hex 00). Otherwise, this is the same behaviour as the world.Base64Encode function.

eg.

print (utils.base64encode ("Nick Gammon")) --> TmljayBHYW1tb24=

The output string will be 4/3 times as large as the input string, plus some possible padding to make up the result to a multiple of 4 (the padding character is "="). Also, if you request linebreaks there will be a further 2 byte for every 76 bytes output (that is, every 57 bytes of input). The default is to not have linebreaks.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.base64encode)


utils.callbackslist

Lua function

utils.callbackslist

Summary

Returns a table of plugin callback function names

Prototype

t = utils.callbackslist ()

Description

This returns a table of all the internal plugin callback function names.

This could be used to detect whether or not a particular callback was available in this version of MUSHclient.

Example:

table.foreachi (utils.callbackslist (), print)

-->

1 OnPluginBroadcast

2 OnPluginChatAccept

3 OnPluginChatDisplay

4 OnPluginChatMessage

5 OnPluginChatMessageOut

6 OnPluginChatNewUser

7 OnPluginChatUserDisconnect

8 OnPluginClose

9 OnPluginCommand

10 OnPluginCommandChanged

11 OnPluginCommandEntered

12 OnPluginConnect

...

41 OnPluginTick

42 OnPluginTrace

43 OnPluginWorldOutputResized

44 OnPluginWorldSave

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.callbackslist)


utils.choose

Lua function

utils.choose

Summary

Display a combo box with choices in it

Prototype

result = utils.choose  (msg, title, tbl, default)

Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a combo-box. If the user cancels the dialog box, or does not make a selection, nil is returned. Otherwise the key of the selected item is returned.

There are three similar functions that have the same arguments:

  •	utils.choose - displays a dialog box with a combo-box in it (drop-down list)

  •	utils.listbox - displays a dialog box with a list control in it - single selection

  •	utils.multilistbox - displays a dialog box with a list control in it - multiple selections allowed

The utils.listbox function would be more suitable for longer lists, but that is probably partly personal preference.

The utils.multilistbox function allows multiple selections, so this is useful when you want the user to be able to select multiple items.

The calling sequence is:

result = utils.choose ( msg, title, t, default )

The only required arguments are the message text and the table of choices (t).

  •	msg = message to display (max 1000 characters)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)

  •	t - table of key/value pairs, as described below

  •	default = default key - defaults to no selection

Return value = the key of what they selected, or nil if cancelled, or nothing selected.

The third argument is a table of key/value pairs. The value is displayed, however the corresponding key is returned. The values are automatically sorted into ascending alphabetic order.

The fourth argument is the key (string or number) which corresponds to the wanted default selection. If it does not correspond to any key in the table then no item will be selected. For no default selection just pass nil as the default.

Example:

print (utils.choose ("Your favourite", "Foods ...", { "apples", "bananas", "peaches", "cream" } ))

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	1 - apples chosen

  •	2 - bananas chosen

  •	3 - peaches chosen

  •	4 - cream chosen

(Note that peaches would actually be shown 4th in the list as the list is sorted).

To convert from the key back to the value, simply index into your table. Eg.

t = { "apples", "bananas", "peaches", "cream" }

result = utils.choose ("Your favourite", "Foods ...", t)

if result then

  print ("You chose", t [result])

else

  print "Nothing chosen"

end -- if

Keys and values can be either strings or numbers. MUSHclient will distinguish between strings and numbers which are the same (eg. "10" and 10 are considered different keys).

Here is an example of using string keys, and supplying a default choice:

t = {

    fruit = "apple",

    vegetable = "potato",

    spice = "pepper",

    herb = "parsley",

    }

result = utils.choose ("Choose a food", "Foods ...", t, "fruit")

if result then

  print ("You chose key", result, "which is", t [result])

else

  print "Nothing chosen"

end -- if

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	"fruit" - apple chosen

  •	"vegetable" - potato chosen

  •	"spice" - pepper chosen

  •	"herb"  - parsley chosen

The return value will be one of the following types:

  •	nil - if no selection made or dialog cancelled

  •	string - if an item with a string key is selected

  •	number - if an item with a numeric key is selected

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.choose)


utils.colourcube

Lua function

utils.colourcube

Summary

Changes the colour cube used by 256-colour ANSI codes

Prototype

utils.colourcube (which)

Description

There are (at least) two colour cubes which can be used to generate the 216 colours used by 256-colour ANSI. (6 * 6 * 6 = 216). The other colours are fixed: 16 "standard ANSI" colours plus 24 gray-scale ones.

This function lets you choose between the Xterm cube (the default) which favours brighter colours (the gap between colours is: 95 / 40 / 40 / 40) and the Netscape cube which has even colours, with a consistent gap of 51 / 51 / 51 / 51 / 51.

utils.colourcube (1)  -- Use the Xterm cube

utils.colourcube (2)  -- Use the Netscape cube

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.colourcube)


utils.compress

Lua function

utils.compress

Summary

Compress a string

Prototype

s = utils.compress (s [, method] )

Description

Compresses string s and returns the compressed form. Note that it may contain nulls (bytes with a zero value).

The optional argument 'method' indicates the level of compression you want.

•	0 = no compression

•	1 = best speed

....

•	9 = best compression

The default, if omitted, is 6.

eg.

comp = utils.compress ("this is a fine thing")

For short strings the compressed data may be longer than the uncompressed data because of a 12-byte "compression information" header that is prepended to the compressed data. For longer text (such as the section above about the Lua sandbox), the compression ratio is about 50%.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.compress)


utils.decompress

Lua function

utils.decompress

Summary

Decompress a string

Prototype

s = utils.decompress (s)

Description

Decompresses string s and returns the decompressed form. Raises an error if decompression cannot be done (eg. bad compressed data).

The two functions utils.compress and utils.decompress should be complementary, so that this should always be true:

x = "some string" -- for any (string) data whatsoever

y = utils.decompress (utils.compress (x)) --> y should be same as x

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.decompress)


utils.directorypicker

Lua function

utils.directorypicker

Summary

Invokes the Windows standard "directory picker" dialog box

Prototype

directoryname = utils. directorypicker (title, initial)

Description

This invokes the Windows standard "directory picker" dialog box, which lets you choose a directory. Usage is:

directoryname = utils. directorypicker (title, initial)

•	title - title to appear on the dialog box (eg. "Directory for backups")

•	initial  - initial directory - if omitted the current directory is used

All arguments are optional.

Returns nil if dialog dismissed, or the chosen directory if not.

The directory name returned will not have a trailing backslash.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.directorypicker)


utils.editbox

Lua function

utils.editbox

Summary

Display a large message box and get free-format reply

Prototype

result = utils.editbox ( msg, title, default, font, fontsize, extras )

Description

This is almost identical to utils.inputbox, except that the response field:

•	is much larger - for entering large amounts of text

•	has scroll bars - for scrolling through it

Otherwise, the arguments are the same as for utils.inputbox.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.editbox)


utils.edit_distance

Lua function

utils.edit_distance

Summary

Returns the Levenshtein Edit Distance between two words

Prototype

n = utils.edit_distance (word1, word2)

Description

This returns the Levenshtein Edit Distance between the two words. This is the same behaviour as the world.EditDistance function.

This could be used in a spell checker to work out how close a misspelt word is to a correctly spelt one.

eg.

print (utils.edit_distance ("food", "fodder"))  --> 3

The Levenshtein distance between two strings  is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character.

For example, the Levenshtein distance between "kitten" and "sitting" is 3, since the following three edits change one into the other, and there is no way to do it with fewer than three edits:

   1. kitten --> sitten (substitution of 's' for 'k')

   2. sitten --> sittin (substitution of 'i' for 'e')

   3. sittin --> sitting (insert 'g' at the end).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.edit_distance)


utils.filepicker

Lua function

utils.filepicker

Summary

Invokes the Windows standard "file picker" dialog box

Prototype

filename = utils.filepicker (title, name, extension, filter, save)

Description

This invokes the Windows standard "file picker" dialog box, which lets you choose a file for opening or saving. Usage is:

filter = { txt = "Text files", ["*"] = "All files" }

filename = utils.filepicker (title, name, extension, filter, save)

•	title - title to appear on the dialog box (eg. "Name of plugin")

•	name  - default name of file to be loaded/saved

•	extension - default extension to use

•	filter - table of file filters, see example above

•	save - true for a "save" dialog, false for a "load" dialog

All arguments are optional.

Returns nil if dialog dismissed, or the chosen filename if not.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.filepicker)


utils.filterpicker

Lua function

utils.filterpicker

Summary

Display a dialog box which filters its contents as you type

Prototype

result = utils.filterpicker  (tbl, title, initial_filter, no_sort, filter_function, filter_prepare_function)

Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a multi-column table. If the user cancels the dialog box, or does not make a selection, nil is returned. Otherwise the key of the selected item is returned.

There is a "filter" box, which if you type into, reduces the visible contents of the dialog to whatever matches the filter (not case-sensitive). This could be used to reduce the displayed items to (for example) shops.

More examples, explanations, and screenshots are at:

http://mushclient.com/forum/?id=10618

The calling sequence is:

result = utils.filterpicker (t, title, initial_filter)

The only required arguments is the table of choices (t).

  •	t - table of key/value pairs, as described below

  •	title = title of box - if nil, defaults to "Filter" (max 100 characters)

  •	initial_filter = initial filter value - defaults to no filter

  •	no_sort - if true, the list is not sorted alphabetically

  •	filter_function - optionally filter dynamically based on a function call.

  •	filter_prepare_function - function called each time something is typed into the filter box.

Return value = the key of what they selected, or nil if cancelled, or nothing selected.

The first argument is a table of key/value pairs. The value is displayed, however the corresponding key is returned. The values are automatically sorted into ascending alphabetic order.

The third argument is the initial value for the filter box. If empty, no filtering initially takes place.

The fourth argument suppresses sorting of the list, if true.

The fifth argument (filter_function) lets you decide at run-time via a function call whether or not to show each item.

This function is passed the current filter (what is wanted), the key of the item in question, and the value of the item in question.

So, for example, if you wanted the filter field to contain a number which indicated the length of words to be shown, you might write:

function filter_function (wanted, key, value)

  local length = tonumber (wanted)

  if not length then

     return false

  end -- if not number

  return #value == length

end -- filter

Every time the user types something into the "filter" box the filter function is called once for every item in the key/value table (to see if the item should be displayed).

The sixth argument (filter_prepare_function) lets you prepare for filtering. This is called once every time the user types something into the "filter" box. This could be used to do a FTS (full text search) of a database, based on the filter text, to find all matching rows. Then the filter function itself would simply see if a row had been found or not.

For example:

function filter_prepare_function (wanted)

  wanted_rooms = {}

  for row in db:nrows ("SELECT uid FROM rooms WHERE name MATCH '" .. wanted .. "'") do

    wanted_rooms [row.uid] = true

  end

end -- filter_prepare_function

Example of use:

print (utils.filterpicker ({ "apples", "bananas", "peaches", "cream" }, "Foods ..." ))

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	1 - apples chosen

  •	2 - bananas chosen

  •	3 - peaches chosen

  •	4 - cream chosen

(Note that peaches would actually be shown 4th in the list as the list is sorted).

To convert from the key back to the value, simply index into your table. Eg.

t = { "apples", "bananas", "peaches", "cream" }

result = utils.filterpicker (t, "Foods ...")

if result then

  print ("You chose", t [result])

else

  print "Nothing chosen"

end -- if

Keys and values can be either strings or numbers. MUSHclient will distinguish between strings and numbers which are the same (eg. "10" and 10 are considered different keys).

Here is an example of using string keys:

t = {

    fruit = "apple",

    vegetable = "potato",

    spice = "pepper",

    herb = "parsley",

    }

result = utils.filterpicker (t, "Foods ...")

if result then

  print ("You chose key", result, "which is", t [result])

else

  print "Nothing chosen"

end -- if

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	"fruit" - apple chosen

  •	"vegetable" - potato chosen

  •	"spice" - pepper chosen

  •	"herb"  - parsley chosen

The return value will be one of the following types:

  •	nil - if no selection made or dialog cancelled

  •	string - if an item with a string key is selected

  •	number - if an item with a numeric key is selected

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.filterpicker)


utils.fontpicker

Lua function

utils.fontpicker

Summary

Invokes the Windows standard "font picker" dialog box

Prototype

wanted_font = utils.fontpicker (name, size, colour)

Description

This invokes the Windows standard "font picker" dialog box, which lets you choose a font from those installed on your system.

wanted_font = utils.fontpicker (name, size, colour)

•	name - preferred name (eg. name of the currently-selected font)

•	size  - preferred size in points

•	colour - preferred colour as an RGB colour

All arguments are optional.

Returns nil if dialog dismissed, or the chosen font details (see below) if not.

If not dismissed, the font details are returned as a table, with the following entries:

•	name - chosen name (eg. "Comic Sans MS")

•	size  - size in points (eg. 12)

•	colour - colour as an RGB colour code  (eg. 0 for black)

•	charset - character set code

•	underline  - 1 if underline chosen, 0 if not

•	strikeout - 1 if strikeout chosen, 0 if not

•	italic  - 1 if italic chosen, 0 if not

•	bold - 1 if bold chosen, 0 if not

•	 style - the style as a string (eg. "Bold Italic")

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.fontpicker)


utils.fromhex

Lua function

utils.fromhex

Summary

Convert a string from hex

Prototype

s = utils.fromhex (s)

Description

This converts the supplied hexadecimal string s back to a normal string. The converted string may contain binary zeroes.

eg.

print (utils.fromhex ("4E69636B2047616D6D6F6E")) --> Nick Gammon

The supplied string may contain 'space' characters (0x09 – 0x0D or 0x20) which are ignored, otherwise if it contains characters other than A-F, a-f or 0-9 this function raises an error. If the number of characters is odd then the last character is treated as the low-order nibble of the final byte. eg.

a = utils.fromhex ("ABC") --> same as utils.fromhex ("AB0C")

Note that "spaces are ignored" means that a sequence like "A B C D" is treated as the same as "ABCD" not "0A 0B 0C 0D".

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.fromhex)


utils.functionlist

Lua function

utils.functionlist

Summary

Returns a table of MUSHclient world function names

Prototype

t = utils.functionlist ()

Description

This returns a table of all the internal MUSHclient function names (the same list used by the Help script function).

The intention here is that you could use this table in an internal Notepad "global replace" to fix the capitalization of function names. You could also use it go generate keywords for use in text editors such as SciTE.

Example:

table.foreachi (utils.functionlist (), print)

-->

1 Accelerator

2 AcceleratorList

3 Activate

4 ActivateClient

5 ActivateNotepad

6 AddAlias

...

296 WorldName

297 WorldPort

298 WriteLog

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.functionlist)


utils.getfontfamilies

Lua function

utils.getfontfamilies

Summary

Returns all fonts available to Windows

Prototype

fonts = utils.getfontfamilies ()

Description

This lets you find the names of all the fonts installed on your current system.

The intention here is for scripts to decide if a font is available, before setting the output or command window to use that font.

For example:

t = utils.getfontfamilies ()

for font in pairs (t) do

  print (font)

end

--> Output:

Lucida Console

Comic Sans MS

Georgia

Mangal

WST_Engl

Wingdings

Sylfaen

Franklin Gothic Medium

Courier

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.getfontfamilies)


utils.glyph_available

Lua function

utils.glyph_available

Summary

Returns the glyph index of a glyph (character) in a font

Prototype

n = utils.glyph_available (font, glyph)

Description

This lets you test if a particular glyph can be rendered in the specified font. This lets a script writer see if a suitable Unicode font has been installed when using UTF-8 mode.

For example:

print (utils.glyph_available ("Arial Unicode MS", 0x2710) )  --> 4439

Zero will be returned if the glyph is not in the font. Nil will be returned if the gdi32 DLL cannot be loaded or if the function GetGlyphIndicesW is not available from Windows.

The number 31 might be returned which probably indicates that the glyph is not in that font.

Other numbers (other than nil, 0 or 31) would indicate that the glyph is available. The exact number represents the "glyph index" in the font table.

Note that it appears that even if 0 is returned that character might be rendered anyway because Windows uses a "fallback" font if a character is not available in the main font. However whether or not this works seems to depend on what main font is selected (for example, if it is a Unicode font or not).

The intention of this function is to let script (plugin) writers warn users if they are planning to use certain glyphs (for example, mapping symbols) which are not in the currently-selected font.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.glyph_available)


utils.hash

Lua function

utils.hash

Summary

Hash a string, returning the hex codes

Prototype

s = utils.hash (s)

Description

Returns a 40-character hex string which is the hash of the string 's'. The string 's' may contain the null byte (ie. hex 00). Otherwise, this is the same behaviour as the world.Hash function.

eg.

print (utils.hash ("Nick Gammon")) --> fe09b07227a4e006213ac005831d55b20508a568

print (Hash ("Nick Gammon")) --> fe09b07227a4e006213ac005831d55b20508a568

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.hash)


utils.info

Lua function

utils.info

Summary

Information about directories, locale, etc.

Prototype

t = utils.info ()

Description

This returns a table with the following things in it:

•	"current_directory" --> the current directory

•	"app_directory" --> the directory in which MUSHclient.exe resides

•	"world_files_directory" -->> the default world files directory

•	"log_files_directory" --> the default log files directory

•	"plugins_directory" --> the default plugins directory

•	"startup_directory" --> the MUSHclient startup directory

•	"locale" --> current locale identifier (eg. EN)

•	"fixed_pitch_font" --> font used for fixed-pitch dialogs

•	"fixed_pitch_font_size" --> point size of font used for fixed-pitch dialogs

•	"translator_file" --> file used for translating messages

This function is primarily intended for situations where you do not have access to the world "Info" functions, such as in the spell-checker.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.info)


utils.infotypes

Lua function

utils.infotypes

Summary

Returns a table of all GetInfo type selectors

Prototype

t = utils.infotypes ()

Description

This returns a table with a description corresponding to each GetInfo selector.

For example:

print (utils.infotypes () [112], GetInfo (112))  --> Automapper active false

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.infotypes)


utils.inputbox

Lua function

utils.inputbox

Summary

Display a message box and get free-format reply

Prototype

result = utils.inputbox ( msg, title, default, font, fontsize, extras )

Description

This lets you display a Windows message box and accept a free-format reply (very similar to InputBox in VBscript). The intention is to allow you to display (in a small dialog box) a question and accept a typed response.

The calling sequence is:

result = utils.inputbox ( msg, title, default, font, fontsize, extras )

The only required argument is the message text itself.

  •	msg = message to display (max 1000 characters)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)

  •	default = default text - defaults to no text

  •	font = font to use in response field - defaults to standard Windows font

  •	fontsize = size of font to use (ignored if no font supplied)

  •	extras = table of extra parameters

The extra parameters (if supplied) is a table which can consist of one or more of:

  •	box_width         --> width of message box in pixels (min 180)

  •	box_height        --> height of message box in pixels (min 125)

  •	prompt_width      --> width of prompt text in pixels (min 10)

  •	prompt_height     --> height of prompt text in pixels (min 12)

  •	reply_width       --> width of reply in pixels (min 10)

  •	reply_height      --> height of reply in pixels (min 10)

  •	max_length        --> max characters they can type (min 1)

  •	validate          --> validation function

  •	ok_button         --> what text to put on the OK button (default: OK)

  •	cancel_button     --> what text to put on the Cancel button (default: Cancel)

  •	ok_button_width    --> the width of the OK button in pixels (default: 75)

  •	cancel_button_width--> the width of the Cancel button in pixels (default: 75)

  •	read_only         --> if true, input area is read-only

  •	no_default        --> if true, pressing <enter> does not dismiss the dialog

Examples of the extra parameters can be found here:

http://gammon.com.au/forum/?id=10644

The validate function (if used) should be a Lua function that takes a single argument (which is what was typed into the input box) and returns true if this reply was acceptable, and false if not. For example, you might return true if the reply was numeric, if a number was required. This function is called when they click the OK button.

Return value = what they typed, or nil if cancelled

Example:

print (utils.inputbox ("What is your name?", "Query", "Nick", "Courier", 9)) --> Peter

There is also similar function which will handle a larger response: utils.editbox

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.inputbox)


utils.listbox

Lua function

utils.listbox

Summary

Display a dialog box with choices in it in a single selection list box

Prototype

result = utils.listbox (msg, title, tbl, default)

Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a single-selection listbox. If the user cancels the dialog box, or does not make a selection, nil is returned. Otherwise the key of the selected item is returned.

There are three similar functions that have the same arguments:

  •	utils.choose - displays a dialog box with a combo-box in it (drop-down list)

  •	utils.listbox - displays a dialog box with a list control in it - single selection

  •	utils.multilistbox - displays a dialog box with a list control in it - multiple selections allowed

The utils.listbox function would be more suitable for longer lists, but that is probably partly personal preference.

The utils.multilistbox function allows multiple selections, so this is useful when you want the user to be able to select multiple items.

The calling sequence is:

result = utils.listbox ( msg, title, t, default )

The only required arguments are the message text and the table of choices (t).

  •	msg = message to display (max 1000 characters)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)

  •	t - table of key/value pairs, as described below

  •	default = default key - defaults to no selection

Return value = the key of what they selected, or nil if cancelled, or nothing selected.

The third argument is a table of key/value pairs. The value is displayed, however the corresponding key is returned. The values are automatically sorted into ascending alphabetic order.

The fourth argument is the key (string or number) which corresponds to the key of the wanted default selection. If it does not correspond to any key in the table then no item will be selected. For no default selection just pass nil as the default.

Example:

print (utils.listbox ("Your favourite", "Foods ...", { "apples", "bananas", "peaches", "cream" } ))

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	1 - apples chosen

  •	2 - bananas chosen

  •	3 - peaches chosen

  •	4 - cream chosen

(Note that peaches would actually be shown 4th in the list as the list is sorted).

To convert from the key back to the value, simply index into your table. Eg.

t = { "apples", "bananas", "peaches", "cream" }

result = utils.listbox ("Your favourite", "Foods ...", t)

if result then

  print ("You chose", t [result])

else

  print "Nothing chosen"

end -- if

Keys and values can be either strings or numbers. MUSHclient will distinguish between strings and numbers which are the same (eg. "10" and 10 are considered different keys).

Here is an example of using string keys, and supplying a default choice:

t = {

    fruit = "apple",

    vegetable = "potato",

    spice = "pepper",

    herb = "parsley",

    }

result = utils.listbox ("Choose a food", "Foods ...", t, "fruit")

if result then

  print ("You chose key", result, "which is", t [result])

else

  print "Nothing chosen"

end -- if

Possible returned values would be:

  •	nil - if no choice made or dialog cancelled

  •	"fruit" - apple chosen

  •	"vegetable" - potato chosen

  •	"spice" - pepper chosen

  •	"herb"  - parsley chosen

The return value will be one of the following types:

  •	nil - if no selection made or dialog cancelled

  •	string - if an item with a string key is selected

  •	number - if an item with a numeric key is selected

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.listbox)


utils.md5

Lua function

utils.md5

Summary

Hash a string using the 128-bit MD5 algorithm

Prototype

s = utils.md5 (s)

Description

This returns a 128-bit MD5 hash of the string s, which may contain binary zeroes. Unlike the utils.hash function this returns the result as a straight 16-byte (128-bit) field (that is, not converted to printable hex). If you want it in readable form you must then convert it yourself (eg. with utils.tohex).

eg.

print (utils.tohex (utils.md5 ("nick gammon")))

--> result: 9A380FD967D936AC99ED73B4A038CE8C

You can write a small Lua program to do the same thing that the md5sum program does (in Linux, Cygwin etc.):

f = io.open ("docs/RegularExpressions.txt", "rb")

if f then

  print (utils.tohex (utils.md5 (f:read ("*a"))))

  f:close ()

end -- if

--> result: 3764E22E2AC5BA67997C42C288253101

Compare this to the output from md5sum using Cygwin:

$ md5sum RegularExpressions.txt

3764e22e2ac5ba67997c42c288253101 *RegularExpressions.txt

The hash is the same, apart from not being in lower case, which you can change with the string.lower function if you want.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.md5)


utils.menufontsize

Lua function

utils.menufontsize

Summary

Alters the size of the font used in menus

Prototype

oldSize = utils.menufontsize (newSize)

Description

For the benefit of players with large monitors, you can set the font size for MUSHclient menus, for example:

  oldSize = utils.menufontsize (15)

The font size must be in the range 5 to 30 (points). Other sizes will be ignored.

In any event, the function returns what the font size was previously. Note that this will probably affect all applications, not just MUSHclient.

You may want to remember the old font size, and restore the menu font size when MUSHclient loses the focus. On my system, the "normal" size was 11 points.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.menufontsize)


utils.metaphone

Lua function

utils.metaphone

Summary

Returns metaphones (sound-alike codes) for the supplied word

Prototype

m1, m2 = utils.metaphone (word)

Description

This returns one or two metaphones (sound-alike codes) for the supplied word. This is the same behaviour as the world.Metaphone function, except that this one returns the secondary metaphone as a separate result.

eg.

print (utils.metaphone ("swordfish"))  --> SRTF XRTF

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.metaphone)


utils.msgbox

Lua function

utils.msgbox

Summary

Display a message box and get a response

Prototype

response = utils.msgbox ( msg, title, type, icon, default )

Description

This lets you display a Windows message box (very similar to MsgBox in VBscript). The intention is to allow you to display (in a small dialog box), information of an urgent nature, or ask a yes/no type question.

The calling sequence is:

result = utils.msgbox ( msg, title, type, icon, default )

The only required argument is the message text itself, the others default to their first possible value. The first 4 arguments are string arguments, the last is a number.

  •	msg = message to display (max 1000 characters)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)

  •	type = type of box (must be in lower case and exactly as shown here):

  •	"ok" - The message box contains one push button: OK. This is the default.

  •	"abortretryignore" - The message box contains three push buttons: Abort, Retry, and Ignore.

  •	"okcancel" - The message box contains two push buttons: OK and Cancel.

  •	"retrycancel" - The message box contains two push buttons: Retry and Cancel.

  •	"yesno" - The message box contains two push buttons: Yes and No.

  •	"yesnocancel" - The message box contains three push buttons: Yes, No, and Cancel.

  •	icon = type of icon:

  •	"!" - An exclamation-point icon appears in the message box. This is the default.

  •	"?" - A question-mark icon appears in the message box.

  •	"i" - An icon consisting of a lowercase letter i in a circle appears in the message box.

  •	"." - A stop-sign icon appears in the message box.

  •	default = default button (1 - 3)

This sets the default button (the one with the focus) to be either button 1, 2 or 3. The default is the first button.

Return value = (string) yes, no, ok, retry, ignore, cancel, abort

Example:

print (utils.msgbox ("You are being paged", "Warning!", "ok", "!", 1)) --> ok

print (utils.msgbox ("You are being paged")) --> ok

print (utils.msgbox ("Go ahead?", "Question", "yesno", "?")) --> yes / no

See also utils.umsgbox if you want to display a message in Unicode (UTF-8).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.msgbox)


utils.multilistbox

Lua function

utils.multilistbox

Summary

Display a dialog box with choices in it in a multiple selection list box

Prototype

result = utils.multilistbox (msg, title, tbl, default)

Description

This displays a dialog box with a predetermined list of items for the user to choose from, in the form of a multiple-selection listbox. If the user cancels the dialog box, or does not make a selection, nil is returned. Otherwise the key of the selected item is returned.

There are three similar functions that have the same arguments:

  •	utils.choose - displays a dialog box with a combo-box in it (drop-down list)

  •	utils.listbox - displays a dialog box with a list control in it - single selection

  •	utils.multilistbox - displays a dialog box with a list control in it - multiple selections allowed

The utils.listbox function would be more suitable for longer lists, but that is probably partly personal preference.

The utils.multilistbox function allows multiple selections, so this is useful when you want the user to be able to select multiple items.

The calling sequence is:

result = utils.multilistbox ( msg, title, t, default )

The only required arguments are the message text and the table of choices (t).

  •	msg = message to display (max 1000 characters)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters)

  •	t - table of key/value pairs, as described below

  •	default = table of default keys (nil for no default selection)

Return value = a table of the selected keys, or nil if nothing selected.

The third argument is a table of key/value pairs. The value is displayed, however the corresponding key is returned. The values are automatically sorted into ascending alphabetic order.

The fourth argument is a table of the keys of the wanted defaults. For no default selection just pass nil as the default.

Example:

t = {

    fruit = "apple",

    vegetable = "potato",

    spice = "pepper",

    herb = "parsley",

    }

defaults = {

    fruit = true,

    spice = true,

    }

result = utils.multilistbox (

    "Choose a food",

    "Foods ...",

    t,

    defaults

    )

Possible returned values would be:

  •	nil - if dialog cancelled

  •	otherwise a table of chosen items (eg. { spice = true, fruit = true } ) - this table might be empty if nothing was chosen

Keys and values can be either strings or numbers. MUSHclient will distinguish between strings and numbers which are the same (eg. "10" and 10 are considered different keys).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.multilistbox)


utils.readdir

Lua function

utils.readdir

Summary

Read a disk directory into a table

Prototype

t = utils.readdir (s)

Description

You can use utils.readdir to read an entire directory on your PC into a Lua table, based on the wildcard you supply.

For example:

t, e = utils.readdir ("c:/mushclient/plugins/*.xml")

assert (t, e) -- raises error on failure

If the directory specification is matched, the result from the call is a table of directory items, keyed by the filename. If the directory specification cannot be matched, or is invalid, it returns nil followed by an error message. You can simply test for non-nil, or call "assert" to report the error.

For each file in the directory (that matches the wildcard) the following is returned:

•	size - file size in bytes

•	create_time - creation time (except for FAT filesystems, where it is omitted)

•	access_time - last access time (except for FAT filesystems, where it is omitted)

•	write_time - time written

•	archive - true if archive. Set whenever the file is changed, and cleared by the BACKUP command.

•	hidden - hidden file. Not normally seen with the DIR command

•	normal - normal file. File can be read or written to without restriction.

•	readonly - read-only. File cannot be opened for writing, and a file with the same name cannot be created.

•	directory - Subdirectory.

•	system - system file. Not normally seen with the DIR command.

By detecting suddirectories you could conceivably recurse and find the contents of subdirectories as well.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.readdir)


utils.reload_global_prefs

Lua function

utils.reload_global_prefs

Summary

Forces global preferences file to be reloaded

Prototype

utils.reload_global_prefs ()

Description

This forces the reload of the global preferences from the disk database. For example, after using the sqlite3 functions to modify one of them.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.reload_global_prefs)


utils.sendtofront

Lua function

utils.sendtofront

Summary

Bring a window to the front

Prototype

found = utils.sendtofront (name)

Description

Brings a nominated Windows window to the front - that is, it activates it.

This could be used to activate an editor, an email program, etc.

eg.

utils.sendtofront ("Crimson Editor")

It returns true if such a window exists, and false if not.

The name is case-sensitive, however only the first part matches (eg. the example above would match on "Crimson Editor - myfile.txt")

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.sendtofront)


utils.sha256

Lua function

utils.sha256

Summary

Hash a string using a 256-bit hash

Prototype

s = utils.sha256 (s)

Description

This returns a 256-bit SHA hash (Secure Hash Algorithm) of the string s, which may contain binary zeroes. Unlike the utils.hash function this returns the result as a straight 32-byte (256-bit) field (that is, not converted to printable hex). If you want it in readable form you must then convert it yourself (eg. with utils.tohex).

eg.

print (utils.tohex (utils.sha256 ("nick gammon")))

--> result: B3223193E1C89CB1E42E2BE2DF34874320F43E149DC315A381B08B7BC52849AD

This is a more secure hash than the standard utils.hash algorithm, which returns a 160-bit hash.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.sha256)


utils.shellexecute

Lua function

utils.shellexecute

Summary

Executes a Windows "shell" command

Prototype

ok, error = utils.shellexecute (filename, params, defdir, operation, show_command)

Description

Only the first argument (filename) is required, the rest are optional.

filename:  The file to open or print or the folder to open or explore.

  The function can open an executable file or a document file.

  The function can print a document file.

params:    A string that specifies the parameters to be passed to the application.

  If filename specifies a document file, params should be nil or "".

defdir:    A string that specifies the default directory.

operation: The following operation strings are valid:

 "open":  The function opens the file specified by the filename parameter.

          The file can be an executable file or a document file. It can also be a folder.

 "print": The function prints the file specified by filename.

          The file should be a document file.

          If the file is an executable file, the function opens the file,

          as if "open" had been specified.

 "explore":  The function explores the folder specified by filename.

  This parameter can be nil or "".

  In that case, the function opens the file specified by filename.

show_command: If filename specifies an executable file, show_command specifies how the application is to be shown when it is opened.

  This parameter can be nil in which case it defaults to 1 - the recommended default.

  This parameter can be one of the following values:

   0:  Hides the window and activates another window.

   1:  Activates and displays a window.

       If the window is minimized or maximized, Windows restores it to

       its original size and position.

       An application should specify this flag when displaying the window for the first time.

   2:  Activates the window and displays it as a minimized window.

   3:  Activates the window and displays it as a maximized window.

   4:  Displays a window in its most recent size and position.

       The active window remains active.

   5:  Activates the window and displays it in its current size and position.

   6:  Minimizes the specified window and activates the next top-level window in the z-order.

   7:  Displays the window as a minimized window.

       The active window remains active.

   8:  Displays the window in its current state.

       The active window remains active.

   9:  Activates and displays the window.

       If the window is minimized or maximized, Windows restores it to its original

       size and position.

       An application should specify this flag when restoring a minimized window.

  10:  Sets the show state based on the SW_ flag specified in the STARTUPINFO structure

       passed to theCreateProcess function by the program that started the application.

       An application should call ShowWindow with this flag to set the initial show

       state of its main window.

If sucessful, the function returns true.

If not, it returns nil followed by an error message. You could use "assert" to test for failure.

Examples:

assert (utils.shellexecute ("c:/mushclient/worlds/SMAUG.MCL"))-- document

assert (utils.shellexecute ("http://www.gammon.com.au/"))     -- web page

assert (utils.shellexecute ("mailto:someone@somewhere.com"))  -- open mail client

assert (utils.shellexecute ("c:/", nil, nil, "explore"))      -- explore disk

assert (utils.shellexecute ("c:/readme.txt", nil, nil, "print"))  -- print a file

Warning: If you plan to redirect output (eg. capture a directory listing to a file) you may need to invoke the "cmd" shell. For example:

utils.shellexecute ("cmd", "/C dir > test.txt", GetInfo (68))

You may also want to pass 0 as the fifth argument (hide the window) in order to stop a command window flickering into view and then disappearing, for example:

utils.shellexecute ("cmd", "/C dir > test.txt", GetInfo (68), "open", 0)

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.shellexecute)


utils.spellcheckdialog

Lua function

utils.spellcheckdialog

Summary

Spell-checker dialog

Prototype

action, replacement = utils.spellcheckdialog (word, suggestions)

Description

This invokes a GUI dialog box, intended for use with a spell checker.

It is called with two arguments, the first being the misspelt word, the second being a table of suggested replacement words.

If this dialog is cancelled, utils.spellcheckdialog return nil.

Otherwise, it returns two things (which are strings): action, replacement

The action can be one of:

•	ignore

•	ignoreall

•	add

•	change

•	changeall

The replacement is the replacement word - if the user chose "change" or "changeall" (or double-clicked a suggested word).

eg.

print (utils.spellcheckdialog ("fod", {"food", "fodder"} ))  --> change food

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.spellcheckdialog)


utils.split

Lua function

utils.split

Summary

Split a delimited string into a table

Prototype

t = utils.split (s, delim)

Description

The function utils.split is intended to do the reverse of table.concat. That is, it takes a string and generates a table of entries, delimited by single-character delimiters (such as comma or newline).

Example:

test = "the,quick,brown,dog,jumped"

t = utils.split (test, ",")

tprint (t)

print (table.concat (t, ","))

Output:

1="the"

2="quick"

3="brown"

4="dog"

5="jumped"

the,quick,brown,dog,jumped

You pass utils.split 2 or 3 arguments:

•	The string to be split

•	The single-character delimiter

•	(optional) the maximum number of splits to do

If the 3rd argument is not supplied, or is zero, then the entire string is split. Otherwise, it will be split the number of times you specify. eg.

t = utils.split (test, ",", 2)

tprint (t)

Output:

1="the"

2="quick"

3="brown,dog,jumped"

In this case the remaining text is placed in the 3rd table item.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.split)


utils.timer

Lua function

utils.timer

Summary

Returns the high-resolution timer output

Prototype

secs = utils.timer ( )

Description

This returns the current output from the high-resolution timer (exactly the same as GetInfo (232) ). However this is easier to remember than GetInfo (232) every time you want to time some code.

If the high-performance timer is not available then the output from the lower-resolution timer is returned instead (seconds since midnight (00:00:00), January 1, 1970).

The intention of this is to allow you to time events, for example:

start = utils.timer ()

-- do stuff here

time_taken = utils.timer () - start

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.timer)


utils.tohex

Lua function

utils.tohex

Summary

Convert a string into hex

Prototype

s = utils.tohex (s)

Description

This converts the string s to hexadecimal (printable) form. The string may contain binary zeroes. Use string.lower to make a lower-case version if that is what you prefer.

eg.

print (utils.tohex ("Nick Gammon")) --> 4E69636B2047616D6D6F6E

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.tohex)


utils.umsgbox

Lua function

utils.umsgbox

Summary

Display a message box and get a response (Unicode)

Prototype

response = utils.umsgbox ( msg, title, type, icon, default )

Description

This lets you display a Windows message box (very similar to MsgBox in VBscript). The intention is to allow you to display (in a small dialog box), information of an urgent nature, or ask a yes/no type question.

The calling sequence is:

result = utils.msgbox ( msg, title, type, icon, default )

The only required argument is the message text itself, the others default to their first possible value. The first 4 arguments are string arguments, the last is a number.

  •	msg = message to display (max 1000 characters) - in UTF-8 characters (Unicode)

  •	title = title of box - if nil, defaults to "MUSHclient" (max 100 characters) - in UTF-8 characters (Unicode)

  •	type = type of box (must be in lower case and exactly as shown here):

  •	"ok" - The message box contains one push button: OK. This is the default.

  •	"abortretryignore" - The message box contains three push buttons: Abort, Retry, and Ignore.

  •	"okcancel" - The message box contains two push buttons: OK and Cancel.

  •	"retrycancel" - The message box contains two push buttons: Retry and Cancel.

  •	"yesno" - The message box contains two push buttons: Yes and No.

  •	"yesnocancel" - The message box contains three push buttons: Yes, No, and Cancel.

  •	icon = type of icon:

  •	"!" - An exclamation-point icon appears in the message box. This is the default.

  •	"?" - A question-mark icon appears in the message box.

  •	"i" - An icon consisting of a lowercase letter i in a circle appears in the message box.

  •	"." - A stop-sign icon appears in the message box.

  •	default = default button (1 - 3)

This sets the default button (the one with the focus) to be either button 1, 2 or 3. The default is the first button.

Return value = (string) yes, no, ok, retry, ignore, cancel, abort

Example:

print (utils.umsgbox ("You are being paged", "Warning!", "ok", "!", 1)) --> ok

print (utils.umsgbox ("You are being paged")) --> ok

print (utils.umsgbox ("Go ahead?", "Question", "yesno", "?")) --> yes / no

See also utils.msgbox if you want to display a message in straight ASCII (not Unicode).

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.umsgbox)


utils.utf8convert

Lua function

utils.utf8convert

Summary

Encodes a string into a UTF-8 string

Prototype

s = utils.utf8convert (str)

Description

This encodes a string which is assumed to be non-UTF-8 into a UTF-8 string.

The function returns a string which is the appropriate UTF-8 encoded string.

eg.

print (utils.tohex (utils.utf8convert (string.char (255))))  --> C3BF

This is intended to allow strings in an ANSI code page to be converted into UTF-8. For example, "Ãˆ" (0xC8) would be converted into 0xC3 0x88.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.utf8convert)


utils.utf8decode

Lua function

utils.utf8decode

Summary

Encodes a series of Unicode codes into a UTF-8 string

Prototype

t = utils.utf8decode(s)

Description

This decodes a UTF-8 string into a table of Unicode numbers.

The function returns a (numerically-keyed) table of numbers, one for each Unicode code point found in the UTF-8 string argument. If the string is found to not be valid UTF-8 it returns nil.

eg.

t = utils.utf8decode (utils.fromhex ("E18E88"))

print (t [1])  --> 5000

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.utf8decode)


utils.utf8encode

Lua function

utils.utf8encode

Summary

Encodes a series of Unicode codes into a UTF-8 string

Prototype

s = utils.utf8encode (u1, u2, ...)

Description

This encodes a series of Unicode codes into a UTF-8 string. You can supply any number of arguments, which must be numbers in the range 0 to 2147483647. Any argument can also be a numerically-keyed table, in which case each sequential item (in the range 1 .. n) is also processed. If you supply a table the keys must not have gaps, or any item after the gap will be ignored. By supplying a table you can conveniently supply a large number of codes to be converted.

The function returns a string which is the appropriate UTF-8 encoded string. It raises an error if the arguments cannot be converted to numbers, are out of range, or have decimal places (eg. 5.5).

eg.

print (utils.tohex (utils.utf8encode (5000)))  --> E18E88

print (utils.tohex (utils.utf8encode (5000, 10000))) --> E18E88E29C90

print (utils.tohex (utils.utf8encode ( { 5000, 10000 } ))) --> E18E88E29C90

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.utf8encode)


utils.utf8sub

Lua function

utils.utf8sub

Summary

Returns a substring of a UTF-8 string

Prototype

s = utils.utf8sub (str, start, end)

Description

Returns a substring of the UTF-8 string, starting at index 'start' and ending at index 'end'. Both may be negative to indicate counting from the right. The end point is optional and defaults to -1, which is the entire rest of the string.

For strings where each character has a character code of < 128, the behaviour is identical to string.sub:

utils.utf8sub ("ABCDEF", 2, 3)  --> BC

utils.utf8sub ("ABCDEF", 3)     --> CDEF

utils.utf8sub ("ABCDEF", -1)    --> F

The above examples are straight "ASCII" strings (ie. each byte is < 128), however the behaviour is different to string.sub with UTF-8 strings. For example:

utils.utf8sub (utils.fromhex ("C686C689C69C"), 1, 2)  --> (hex) C686C689

utils.utf8sub (utils.fromhex ("C686C689C69C"), -1, -1)  --> (hex) C69C

For Unicode characters (ie. whose character code is >= 128 and <= 255) then the function calculates the number of bytes that each "Unicode code point" will require, and count each one as a "column".

The supplied string must be valid UTF-8. If not, the function returns nil followed by the byte position in error.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.utf8sub)


utils.utf8valid

Lua function

utils.utf8valid

Summary

Checks if a UTF-8 string is valid

Prototype

n, column = utils.utf8valid (s)

Description

This checks if a UTF-8 string is valid.

This returns the length of the string (in Unicode characters) if the supplied string is valid UTF-8.

Otherwise it returns nil, and the column of the character in error (1-relative).

eg.

print (utils.utf8valid (utils.fromhex ("F5838894FCB5898588B4"))) --> 2

print (utils.utf8valid (utils.fromhex ("f0f0f0"))) --> nil 1

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.xmlread (Parses an XML string into a nested table)

(Help topic: lua=utils.utf8valid)


utils.xmlread

Lua function

utils.xmlread

Summary

Parses an XML string into a nested table

Prototype

t = utils.xmlread (s)

Description

The function utils.xmlread uses MUSHclient's internal XML parser to parse an XML string you supply. This effectively would let you parse triggers, aliases etc. that you have copied to the clipboard as text (or created with ExportXML script routine), and see exactly what each value is set to. Or, by reading a MUSHclient world file into memory as a string, you could parse that.

The XML parser is not necessarily 100% industry-standard XML parsing, however it is the method MUSHclient uses for its own XML documents, and should be reasonably compatible with standard XML unless you use some of the more fancy XML extensions. It should certainly parse the XML output by MUSHclient itself (eg. triggers, aliases, world files, plugins) as that is the same routine it uses to read them in.

You pass to the parser a single string, which is the XML to be parsed. If the parsing is successful three results are returned:

•	The root node (all other nodes are children of this node)

•	The root document name (eg. "muclient")

•	A table of custom entities in the document, or nil if no custom entities

If the parsing fails, three results are returned:

•	nil - to indicate failure

•	The error reason

•	The line the error occurred at

You can pass the first 2 results to "assert" to quickly check if the parsing was successful.

Each node consists of a table with the following entries:

•	name - name of the node (eg. <trigger>foo</trigger> - the name is "trigger")

•	content - contents of the node (eg. <trigger>foo</trigger> - the content is "foo")

•	empty - boolean to indicate if the node is empty. (eg. <br/> is an empty node)

•	line - which line in the XML string the node occurred on (eg. line 5)

•	attributes - a table of attributes for this node, keyed by the attribute name (eg. "world_file_version"="15").

Attribute names have to be unique so we can used a keyed lookup to find them.

The attributes table is not present if there are no attributes defined.

•	nodes - a table of child nodes, keyed by ascending number (the order they appeared in). Each child node has the same contents as described above.

Children are not necessarily unique (eg. there may be more than one <trigger> node in a document) so they are keyed by number, and not by node name.

The nodes table is not present if there are no children of this node.

Example:

a, b, c = utils.xmlread ("<foo><bar x='2'/></foo>")

require "tprint"

tprint (a)

Output:

"line"=1

"name"=""

"nodes":

  1:

    "line"=1

    "name"="foo"

    "nodes":

      1:

        "line"=1

        "name"="bar"

        "empty"=true

        "content"=""

        "attributes":

          "x"="2"

    "content"=""

"content"=""

You can see from the above that the "root" node is really just an unnamed node which is the placeholder for the top level nodes (ie. the first "real" node is a child of the root node). In this case the node "foo" is the first child of the root node.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 utils.activatenotepad (Actvitates the specified notepad window)

 utils.appendtonotepad (Appends text to the specified notepad window)

 utils.base64decode (Decode a string which was base-64 encoded)

 utils.base64encode (Encode a string with base-64 encoding)

 utils.callbackslist (Returns a table of plugin callback function names)

 utils.choose (Display a combo box with choices in it)

 utils.colourcube (Changes the colour cube used by 256-colour ANSI codes)

 utils.compress (Compress a string)

 utils.decompress (Decompress a string)

 utils.directorypicker (Invokes the Windows standard "directory picker" dialog box)

 utils.editbox (Display a large message box and get free-format reply)

 utils.edit_distance (Returns the Levenshtein Edit Distance between two words)

 utils.filepicker (Invokes the Windows standard "file picker" dialog box)

 utils.filterpicker (Display a dialog box which filters its contents as you type)

 utils.fontpicker (Invokes the Windows standard "font picker" dialog box)

 utils.fromhex (Convert a string from hex)

 utils.functionlist (Returns a table of MUSHclient world function names)

 utils.getfontfamilies (Returns all fonts available to Windows)

 utils.glyph_available (Returns the glyph index of a glyph (character) in a font)

 utils.hash (Hash a string, returning the hex codes)

 utils.info (Information about directories, locale, etc.)

 utils.infotypes (Returns a table of all GetInfo type selectors)

 utils.inputbox (Display a message box and get free-format reply)

 utils.listbox (Display a dialog box with choices in it in a single selection list box)

 utils.md5 (Hash a string using the 128-bit MD5 algorithm)

 utils.menufontsize (Alters the size of the font used in menus)

 utils.metaphone (Returns metaphones (sound-alike codes) for the supplied word)

 utils.msgbox (Display a message box and get a response)

 utils.multilistbox (Display a dialog box with choices in it in a multiple selection list box)

 utils.readdir (Read a disk directory into a table)

 utils.reload_global_prefs (Forces global preferences file to be reloaded)

 utils.sendtofront (Bring a window to the front)

 utils.sha256 (Hash a string using a 256-bit hash)

 utils.shellexecute (Executes a Windows "shell" command)

 utils.spellcheckdialog (Spell-checker dialog)

 utils.split (Split a delimited string into a table)

 utils.timer (Returns the high-resolution timer output)

 utils.tohex (Convert a string into hex)

 utils.umsgbox (Display a message box and get a response (Unicode))

 utils.utf8convert (Encodes a string into a UTF-8 string)

 utils.utf8decode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8encode (Encodes a series of Unicode codes into a UTF-8 string)

 utils.utf8sub (Returns a substring of a UTF-8 string)

 utils.utf8valid (Checks if a UTF-8 string is valid)

(Help topic: lua=utils.xmlread)


while

You can make code loop by using while condition do ... end - the test is done at the start of the loop, so if the test fails the loop may not be executed at all.

while danger_threatens () do

  flash_lights ()

end  -- while

If you want to leave the loop from inside you can use a break statement:

while danger_threatens () do

  flash_lights ()

  if enough_flashing () then

    break

  end -- if

end  -- while

The only conditions that are false are the values false and nil - every other value is considered true.

If you want to test at the end of the loop use repeat instead.

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua LPEG library

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua SQLite (database) interface

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assignment (Assignment)

 break (Exit a loop early)

 comments (How to make comments)

 data types (Types of data)

 do (Make a block)

 for (generic) (Loop using an iterator function)

 for (numeric) (Loop with a range of numbers)

 function (Function declaration)

 identifiers (Naming rules)

 if / then / else (If statements)

 keywords (Reserved words)

 local (Local variables)

 logical operators (Logical comparison)

 precedence (Operator precedence)

 relational operators (Comparison)

 repeat (Loop with test at end)

 return (Exit from a function)

 string literals (How to write constant strings)

 tables (Table data types)

(Help topic: lua=while)


xpcall

Lua function

xpcall

Summary

Calls a function with a custom error handler

Prototype

ok, result = xpcall (f, err)

Description

Calls function f with err as the custom error handler.

If an error occurs in f it is caught and the error-handler 'err' is called. Then xpcall returns false, and whatever the error handler returned.

If there is no error in f, then xpcall returns true, followed by the function results from f.

Note that the supplied error function is called before the stack is unwound (in case of error) so this is a good time to find what functions were on the stack leading up to the error. In the example below we use the debug.traceback function, which shows a stack trace as at the time of the error.

function f ()

  return "a" + 2  -- will cause error

end -- f

function err (x)

  print ("err called", x)

  return "oh no!"

end -- err

print (xpcall (f, err))

 -->

err called [string "Immediate"]:2: attempt to perform arithmetic on a string value

false oh no!

function f2 ()

  return 2 + 2

end -- f

print (xpcall (f, err))  --> true 4

function f ()

return "a" + 2

end -- f

print (xpcall (f, debug.traceback))

 -->

false   stdin:2: attempt to perform arithmetic on a string value

stack traceback:

        stdin:2: in function `f'

        [C]: in function `xpcall'

        stdin:1: in main chunk

        [C]: ?

See Also ...

Topics

 Lua base functions

 Lua bc (big number) functions

 Lua bit manipulation functions

 Lua coroutine functions

 Lua debug functions

 Lua io functions

 Lua math functions

 Lua os functions

 Lua package functions

 Lua PCRE regular expression functions

 Lua script extensions

 Lua string functions

 Lua syntax

 Lua table functions

 Lua utilities

 Scripting

 Scripting callbacks - plugins

Lua functions

 assert (Asserts that condition is not nil and not false)

 collectgarbage (Collects garbage)

 dofile (Executes a Lua file)

 error (Raises an error message)

 gcinfo (Returns amount of dynamic memory in use)

 getfenv (Returns the current environment table)

 getmetatable (Returns the metatable for the object)

 ipairs (Iterates over a numerically keyed table)

 load (Loads a chunk by calling a function repeatedly)

 loadfile (Loads a Lua file and parses it)

 loadlib (Loads a DLL (obsolete in Lua 5.1))

 loadstring (Compiles a string of Lua code)

 module (Creates a Lua module)

 next (Returns next key / value pair in a table)

 pairs (Traverse all items in a table)

 pcall (Calls a function in protected mode)

 print (Prints its arguments)

 rawequal (Compares two values for equality without invoking metamethods)

 rawget (Gets the value of a table item without invoking metamethods)

 rawset (Sets the value of a table item without invoking metamethods)

 require (Loads a module)

 select (Returns items in a list)

 setfenv (Sets a function's environment)

 setmetatable (Sets the metatable for a table)

 tonumber (Converts a string (of the given base) to a number)

 tostring (Converts its argument to a string)

 type (Returns the type of a variable)

 unpack (Unpacks a table into individual items)

(Help topic: lua=xpcall)