[Home] [Downloads] [Search] [Help/forum]

Gammon Forum

See www.mushclient.com/spam for dealing with forum spam. Please read the MUSHclient FAQ!

[Folder]  Entire forum
-> [Folder]  MUSHclient
. -> [Folder]  MXP and Pueblo
. . -> [Subject]  Script callback routines
Home  |  Users  |  Search  |  FAQ
Username:
Register forum user name
Password:
Forgotten password?

Script callback routines

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page


Posted by Nick Gammon   Australia  (21,322 posts)  [Biography] bio   Forum Administrator
Date Tue 12 Jun 2001 11:49 PM (UTC)

Amended on Sat 30 Jun 2001 03:19 AM (UTC) by Nick Gammon

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. &lt; )
  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
[Go to top] top

Posted by Nick Gammon   Australia  (21,322 posts)  [Biography] bio   Forum Administrator
Date Reply #1 on Fri 15 Jun 2001 12:42 AM (UTC)

Amended on Mon 27 Aug 2001 01:17 AM (UTC) by Nick Gammon

Message
These are the message numbers used by MUSHclient when calling the "MXP error" script routine.


// error level messages

1000  Unknown                       should not get this
1001  UnterminatedElement           eg. < ... \n
1002  UnterminatedComment           eg. <!-- ... \n
1003  UnterminatedEntity            eg. & ... \n
1004  UnterminatedQuote             eg. < ' ... \n
1005  EmptyElement                  eg. <>
1006  ElementTooShort               eg. <!>
1007  InvalidEntityName             eg. &*;
1008  DefinitionWhenNotSecure       eg. <!ELEMENT ... > in open mode
1009  InvalidElementName            eg. < 2345 >  or </ 2345 >
1010  InvalidDefinition             ie. not <!ELEMENT ...> or <!ENTITY ...>
1011  CannotRedefineElement         cannot redefine inbuilt element
1012  NoTagInDefinition             no < in element definition  eg. <!ELEMENT foo 'bold' >  (should be '<bold>' )
1013  UnexpectedDefinitionSymbol    eg. <!ELEMENT foo '<<bold>' >
1014  NoClosingDefinitionQuote      eg. <!ELEMENT foo '<send "west>' >
1015  NoClosingDefinitionTag        eg. <!ELEMENT foo '<bold' >
1016  NoInbuiltDefinitionTag        defining unknown tag  eg. <!ELEMENT foo '<bar>' >   
1017  NoDefinitionTag               eg. <!ELEMENT foo '<>' >
1018  BadVariableName               variable name in FLAG does not meet MUSHclient rules
1019  UnknownElementInAttlist       ATTLIST for undefined element name
1020  CannotRedefineEntity          cannot redefine inbuilt entity
1021  NoClosingSemicolon            eg. <!ENTITY foo &quot >
1022  UnexpectedEntityArguments     eg. <!ENTITY foo 'bar' xxxx >
1023  UnknownElement                eg. <blah>
1024  ElementWhenNotSecure          eg. <send> in open mode
1025  NoClosingSemicolonInArgument  eg. <!ELEMENT foo '<send &bar>'>
1026  ClosingUnknownTag             closing tag we don't recognise
1027  UnknownColour                 argument to COLOR or FONT not recognised colour
1028  InvalidEntityNumber           eg. &#xxx;
1029  DisallowedEntityNumber        eg. &#5000;
1030  UnknownEntity                 eg. &foo;
1031  InvalidArgumentName           eg. <color 123=blue>  (123 is invalid)
1032  NoArgument                    eg. <font color=>
1033  PuebloOnly                    using Pueblo element in MXP mode
1034  MXPOnly                       using MXP element in Pueblo mode
1035  DefinitionAttemptInPueblo     Pueblo does not support <!ELEMENT> or <!ENTITY>
1036  InvalidSupportArgument        Invalid argument to <support> tag
1037  InvalidOptionArgument         Invalid argument to <option> tag
1038  DefinitionCannotCloseElement  eg. <!ELEMENT foo '</bold>' >
1039  DefinitionCannotDefineElement eg. <!ELEMENT foo '<!ELEMENT>' >

 warning level messages

5000  ReplacingElement          replacing previously-defined element
5001  ManyOutstandingTags       too many unclosed tags 
5002  ArgumentNotSupplied       argument needed but not supplied or blank 
5003  ArgumentsToClosingTag     eg. </send bar > 
5004  OpenTagBlockedBySecureTag when closing an open tag secure tag blocks it 
5005  OpenTagNotThere           eg. </bold> when no opening tag 
5006  TagOpenedInSecureMode     cannot close tag - it was opened in secure mode 
5007  ClosingOutOfSequenceTag   eg. <b> <i> </b>
5008  OpenTagNotInOutputBuffer  opening tag no longer in buffer 
5009  CharacterNameRequestedButNotDefined   no name known - cannot reply to <user>
5010  PasswordNotSent           password requested too late in session
5011  PasswordRequestedButNotDefined    no password known - cannot reply to <pass>
5012  TagNotImplemented         MXP tag known but not implemented 
5013  OpenTagClosedAtEndOfLine  tag closed because \n received 
5014  TagClosedAtReset          tag closed because <reset> received
5015  UnusedArgument            argument supplied but not used  eg. <bold blue> 
5016  NotStartingPueblo         we have received the Pueblo initiation string, but are not starting Pueblo

 information level messages

10000  VersionSent                <version> response sent
10001  CharacterNameSent          <user> response sent 
10002  PasswordSent               <pass> response sent 
10003  ScriptCollectionStarted    collecting <script> text 
10004  ScriptCollectionCompleted  finished collecting <script> 
10005  ResetReceived              <reset> received 
10006  off                        mxp turned off 
10007  on                         mxp turned on 
10008  ModeChange                 security mode changed to/from a permanent state
10009  SupportsSent               <supports> response sent
10010  OptionsSent,               <options> response sent

 other messages ("all" category) - pretty spammy

20000  CollectedElement    received < ... >
20001  CollectedEntity     received & ... ; 
20002  GotDefinition       received <!ELEMENT ...> or <!ENTITY ...> 

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Twisol   USA  (2,257 posts)  [Biography] bio
Date Reply #2 on Tue 17 Nov 2009 01:02 AM (UTC)
Message
Is it possible to set these programmatically instead of from the dialog? Something similar to the OnPlugin* family of callbacks would be great, actually. I couldn't find any references to any MXP handling mechanisms except these dialog fields, so if I missed something, please let me know...

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
[Go to top] top

Posted by Nick Gammon   Australia  (21,322 posts)  [Biography] bio   Forum Administrator
Date Reply #3 on Tue 17 Nov 2009 02:45 AM (UTC)
Message
Can you elaborate? What do you mean by "instead of from the dialog"?

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Twisol   USA  (2,257 posts)  [Biography] bio
Date Reply #4 on Tue 17 Nov 2009 03:12 AM (UTC)
Message
Well, the OnPlugin* family of callbacks are all automatically registered. An OnPluginMXP* family of callbacks would be useful. As it stands, and as far as I know, there can only be one MXP callback registered per MXP event, correct? So multiple plugins can't catch and handle them - and even one plugin handling MXP events seems improbable, given that the callbacks entered into the MXP events dialog appear to be specific to the world's script space only.

So unless I've missed something along the way, a facility to register OnPluginMXP* callbacks programmatically would be helpful, whether it be automatic like the normal OnPlugin* callbacks are, or explicitly set via, say, RegisterMXPCallback("openTag", function() end) (as a very simple example).

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
[Go to top] top

Posted by Nick Gammon   Australia  (21,322 posts)  [Biography] bio   Forum Administrator
Date Reply #5 on Tue 17 Nov 2009 05:00 AM (UTC)
Message
If I understand the question correctly, and I'm not sure I do, you want the MXP callbacks to be available inside a plugin without having to enter them in the script configuration dialog box?

This is already available, in the help for "Scripting callbacks - MXP" it says:

Quote:

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.


So, for example:

Quote:

MXP start tag

This routine is called when a "start" tag is parsed (successfully). For example, "<send href='go west'>".

Inside a plugin: OnPluginMXPopenTag


In other words, inside a plugin, make a script called OnPluginMXPopenTag and it will be called without any registration or other pre-processing.

Now in the case of OnPluginMXPopenTag *all* plugins with that script function in them will be called, unless one of them returns a non-zero value (as documented) which suppresses the tag, and stops further plugins being called.

*Then* the script function registered in the main script file, if any, is called.




- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Twisol   USA  (2,257 posts)  [Biography] bio
Date Reply #6 on Tue 17 Nov 2009 05:35 AM (UTC)
Message
Yes, that's exactly what I meant. I wanted an OnPluginMXP* family of callbacks, and here you're telling me it's already there! *laughs* Thanks, I had hoped I was just missing something.

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
[Go to top] top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.


9,338 views.

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page

Go to topic:           Search the forum


[Go to top] top

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

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

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]