| Posted by
| Nick Gammon
Australia (23,120 posts) Bio
Forum Administrator |
| Message
| 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.
MXP startup
This is called when MXP is started.
sub OnMXPStart
world.Note "MXP started."
end sub
MXP shutdown
This is called when MXP is stopped.
sub OnMXPShutdown
world.Note "MXP stopped."
end sub
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.
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
world.NoteColourName "white", "red"
world.Note level + "(" + cstr (number) + "): " _
+ message
end if
' do not display entities received (eg. < )
if number = 20001 then OnMXPError = 1
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.
MXP start tag
This routine is called when a "start" tag is parsed (successfully). For example, "<send href='go west'>".
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.
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)
dim i
world.AppendToNotepad "MXP", _
"Opening tag: " + name + vbCRLF
world.AppendToNotepad "MXP", _
"Argument list: " + args + vbCRLF
if not IsEmpty (mylist) then
for i = lbound (mylist) to ubound (mylist)
world.AppendToNotepad "MXP", _
"Arg " + cstr (i) + " = " + mylist (i) + vbCRLF
next
End If
' suppress color tags
if name = "color" then OnMXPStartTag = 1
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>".
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.
For example, if you had:
<send>eat newspaper</send>
The value of &text; would be "eat newspaper".
sub OnMXPEndTag (name, text)
world.AppendToNotepad "MXP", _
"Closing tag: " + name + vbCRLF
world.AppendToNotepad "MXP", _
"Text: " + text + vbCRLF
end sub
MXP set variable
This is called when MXP sets a MUSHclient variable (by using the FLAG parameter on an element definition).
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"
sub OnMXPvariable (name, contents)
world.note "Var " + name + " set to " + contents
end sub
|
- Nick Gammon
www.gammon.com.au, www.mushclient.com | | Top |
|
![[Go to top]](/images/gototop.gif){kind=small}
top