This document may be freely copied and distributed, provided that: this copyright notice is included, the entire body of text is included, and the textual content of this document is unchanged.

For written permission to use portions of this document in other publications, send email to bfree@graphcomp.com.

MUTTER(tm) Commands

Note that in MUTT(tm) Lite, these procedures are limited to single line scoping. Future versions will support multi-line scoping via brackets "{}". MUTTER(tm) procedures are nestable and recursive.

In MUTT(tm) Lite, each procedure begins with a label (the script name) and an "=", followed by one or more commands delimited by a ";".

MUTTER(tm) commands may be used in script files or interactively by typing them in the application's command window. Commands typed interactively must be preceeded by a command prefix (the default is ";") to differentiate the command from raw text that is to be send to the mud host.

The following documents two forms of these commands. The first form is the one use in scripting, the second is a more relaxed version for typed entry. The second form (preceeded by the command prefix) may also be used for typed entry.

say( expression [, expression [...]] );
;say expression [, expression [...]]

Sends text to the host. "expression" may be a variable or a string within quotes. The expressions are evaluated, concatenated and then sent with a terminating carriage return and line feed.

put( expression [, expression [...]] );

Similar to "say", except that the expressions are pasted into the command window, but not executed. Anything previously in the command window is overwritten.

putmore( expression [, expression [...]] );

Similar to "put", except that the expressions are appended to the end of the command window, without overwriting previous contents.

set( variable, expression [, expression [...]] );
;set variable, expression [, expression [...]]

Similar to "say", except that the expressions are copied into the specified variable, instead of being sent to the host.

"variable" must be a user-defined variable in the script file.

setword( variable, expression, index );
;setword variable, expression, index

Copies the Nth word of "expression", as indicated by "index", into "variable". A word in this context is any string separated by whitespace; adjacent punctuation is considered part of the word. The "clean" command may be used to remove punctuation.

"variable" must be a user-defined variable in the script file.

"expression" is a string, system variable or a user-defined variable.

"index" is a 1-based number. A positive index indicates the count from the start of "variable"; a negative starts at the back. "index" also may be TRIGGER_INDEX, TRIGGER_PREV or TRIGGER_NEXT.

clean( variable, filter );
;clean variable, filter

Removes characters indicated by "filter" from "variable".

"variable" must be a user-defined variable in the script file.

"filter" may be a string, a system variable or a user-defined variable.

xlat( variable, case_flag, old, new );
;xlat variable, case_flag, old, new

Substitutes occurences of "old" with "new" in "variable".

"variable" must be a user-defined variable in the script file, and must be large enough to hold new string.

"case_flag" is 1 for case-sensitive matching; 0 indicates that the case in "variable" is ignored.

"old" is the string being searched for and may be a string, a system variable or a user-defined variable.

"new" is the string used for replacement and may be "", a string, a system variable or a user-defined variable.

send( file [, file [...]] );
;send file [, file [...]]

Sends the content of "file" to the host. These should be text files containing carriage returns and line feeds.

note( expression [, expression [...]] );
;note expression [, expression [...]]

Echos text to the display window and log files if echo is enabled. "expression" may be a variable or a string within quotes.

popup( expression [, expression [...]] );
;popup expression [, expression [...]]

Similar to "note" except that "expression" is displayed in a popup message box, instead of being executed, echoed or logged.

prompt( variable, default, expression [, expression [...]] );
;prompt variable, default, expression [, expression [...]]

Similar to "popup" except that "expression" is displayed as a prompt in a popup dialog; user input is saved in "variable".

If the user presses the dialog's cancel button, "variable" is untouched and a "break" occurs in the script.

"variable" must be a user-defined variable in the script file.

"default" is used as the default value and may be a string or variable.

clear;
;clear

Clears display window.

log( expression );
;log [expression]

Opens and closes a log file used to record text displayed in the Receive window. "filename" is "", a string or a variable.

If "filename" evaluates to "", the existing log file, if open, is closed.

Note: The Open Log option on the Files menu opens a log file for all sessions. This command opens a separate log file for each session, and is independent of the menu option.

rec( expression );
;rec [expression]

Opens and closes a record file used to record the commands that you send to the mud. This can be used for playback via the "send" command. Note: the record file must be closed before it can be sent. "filename" is "", a string or a variable.

If "filename" evaluates to "", the existing record file, if open, is closed.

do( script );
;do script

Executes a previously defined script.

exec( executable [, parameter [...]] );
;exec executable [, parameter [...]]

Launches a program or a registered document. "executable" is a string or a variable

Example: exec( "notepad", "c:\autoexec.bat" ); Example: exec( "sound\ribbit.wav" );

The second example assumes that .WAV is associated with a .WAV player.

Note: this requires that SHELL.DLL be located in your path. This is automatically installed on WIn3.1 NT, Win95 - you may have to copy it to your OS directory on some platforms. It is available at ftp://ftp.graphcomp.com/pub/msw/mutt/shell.DLL

beep( number );
;beep number

Causes a beep. A negative "number" will play that many beeps. A positive number will play a standard sound associated with that beep number. Refer to your OS documentation on registering various .WAV and .MID sounds to each beep number.

Here are some standard beep numbers:

• STOP=16
• QUESTION=32
• EXCLAMATION=48
• ASTERISK=64

break;
;break

Stops the execution of a script. In the command line, this is a NOP.

term;
;term

Terminates the MU* session.

if( expression ) command [else command];
;if expression command [else command]

Conditionally executes "command". "expression" may be a variable, string or function. "command" may be any of the previously described commands. If the expression evaluates to non-"0", the first command is executed. Otherwise the second command is executed, if provided.

"if" commands may not be directly nested in MUTT(tm) Lite; to nest "if"s, make "command" a "do( script )" where "script" contains another "if" comand.

wait( label, time, ok_script, fail_script );
;wait label, time, ok_script, fail_script

Posts a trigger, "label", that expires in "time" seconds. If the trigger is tripped before expiration, the ok_script is executed; otherwise the fail_script is executed. Either script may be "break"; Calling wait will disable the spcified trigger had it previously been enabled. After wait is either triggered or timed out, but prior to executing the appropriate script, the trigger is disabled.

trigger( label, script );
;trigger label, script

Enables trigger, "label". When the trigger is tripped by received text, the script is executed; the trigger remains enabled. If "script" is "break", the trigger is disabled.

The system variable TRIGGER_LINE is set to a string containing the line that caused the trigger. TRIGGER_INDEX is set to the word number in the line that caused the trigger. These values are overwritten by the next trigger match.

Note: increasing the number of active triggers will reduce the response performance of the app. Triggers can be used most efficiently when a small number of key triggers are used to temporarily initialize other triggers.