Mmucl (pronounced muckle) is a mud client written in Tcl.
Mmucl is maintained by Mark Patton, msp@users.sourceforge.net.
The current developement version of Mmucl, with which this manual was distributed, is 1.5.2.
You can find the latest news at the Mmucl home page, http://mmucl.sourceforge.net.
Mmucl is "free"; this means that everyone is free to use it and free to redistribute it on a free basis. Mmucl is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of Mmucl that they might get from you.
Specifically, I want to make sure that you have the right to give away copies of Mmucl, that you receive source code or else can get it if you want it, that you can change Mmucl or use pieces of it in new free programs, and that you know you can do these things.
To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of Mmucl, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.
Also, for my own protection, I must make certain that everyone finds out that there is no warranty for Mmucl. If Mmucl is modified by someone else and passed on, I want their recipients to know that what they have is not what I distributed, so that any problems introduced by others will no reflect on my reputation.
The precise conditions of the licenses for Mmucl are found in the General Public License that accompanies it.
Mmucl is a MUD (Multi-User Dungeon) client. A MUD is a multi-player role-playing game that runs as a server on a remote host. The server accepts connections, receives input from users, decides what to do, and sends information back.
Most muds are text based. You can connect to and play on them with a simple telnet client, but that tends to be painful. Mud clients make mudding much more pleasant. They let you do all sorts of useful things such as automatically responding to certain patterns of mud output and making shortcuts for often used mud commands.
Mmucl provides the features found in most mud clients such as support for ANSI color, triggers, command line editing, aliases, multi-session support, and macros to name a few. Mmucl's most powerful feature is its extensibility through Tcl scripts. See Scripts, for more info.
Mmucl has a number of different interfaces from text mode to graphical, See Interfaces.
Usage: mmucl [interface] option...
interface indicates which of several interfaces you wish to use, see Interfaces for information.
Options:
-h --help
-v --version
-e --eval scriptThe environment variable TCLLIBPATH can be used to specify
where Mmucl looks for Tcl extensions.
Mmucl has a number of different interfaces, some of which require other libraries installed to run.
tk
tk is a GUI interface that requires Tk. This is the default.
gnome
gnome is a gui interface that requires Tcl-Gtk,
http://tcl-gtk.sourceforge.net, and Gnome2,
http://www.gnome.org. It is by far the prettiest interface.
readline
readline is a basic text interface that requires tclreadline,
http://tclreadline.sourceforge.net
text
text is an extremely simple text interface that works on any terminal.
This is a brief introduction to the basics of using Mmucl.
Most of your interaction with Mmucl will be through the command line.
To connect to a mud, type /connect host port.
Mmucl will try to connect to the mud running on host at port port.
The character / at the beginning of input
indicates that the rest of the string is a command to the client
in the form of a Tcl script, see Scripts.
In this case a procedure,
connect, is executed with host and port as arguments.
The input e;e is equivalent to typing in e twice.
If input begins with \, then input minus the
beginning \ is sent to the mud. You might use this to
avoid the special interpretation of ;.
For example \alias x equip;hide would send alias x equip;hide
to the mud.
If the first word of input matches an alias name, the alias
is executed.
For example if you had an alias k and typed k blob then
the alias would be evaluated with an argument of blob.
For more information on aliases, see alias.
For a more exact description of command line interpretation, see parse.
Here are some examples of useful things Mmucl can do. You may not necessarily understand all the examples, but you should be able to use them as templates and figure out how they work later.
Note that the examples are Tcl scripts. You can use them by typing
/ followed by the script in the client. Alternately, and
much recommended, use a real editor, save them to a file, and
load them with /source file.
Make an alias named h to send the command
cast cure critical wounds me to the mud.
The write procedure sends each of its arguments
to the mud.
alias set h {
write "cast cure critical wounds me"
}
Even better, bind the command to a key. We'll bind it to F1. See key, for more about binding keys.
key set F1 {
write "cast cure critical wounds me"
}
Suppose we want to heal someone else? We'll make an h alias that heals someone else if given an argument and heals us if given no arguments.
The variable $0 is the argument string given to the
alias. The variable $1 is the first word, a sequence
of non-space characters, in $0.
alias set h {
if {$1 ne ""} {
write "cast cure critical wounds $0"
} else {
write "cast cure critical wounds me"
}
}
Maybe we should heal ourselves automatically whenever
we get Bob CRUSHES you to the ground sent from
the mud. Actions execute commands whenever their pattern
matches output from the mud. See action, for more
information.
action set {Bob CRUSHES you to the ground} {
write "cast cure critical wounds me"
}
How about generalizing the action so we get healed
when any monster crushes us? We can use %w in
the pattern to match the monster's name. (If the
monster's name has spaces in it, use %s
instead.) See Format, for a detailed description
of the pattern syntax.
action set {%w CRUSHES you to the ground} {
write "cast cure critical wounds me"
}
One problem with the action is that someone could
give us a tell, Jerk tells you: bear CRUSHES you to the ground
and trigger the action. To prevent that we want
to have the action only be triggered when
%w CRUSHES you to the ground is at the beginning
of a line. We can do that with ^ which matches
the beginning of a line.
action set {^%w CRUSHES you to the ground} {
write "cast cure critical wounds me"
}
Now suppose we want to automatically heal our friends
when they tell us "heal me".
The variable $1 is the first match in the
pattern counting from left to right.
action set {^%w tells you: heal me} {
write "cast cure critical wounds $1"
}
Mmucl is written in the scripting language Tcl and is extendable through that same language. Mmucl makes a great deal of its functionality available to the user through commands it defines. See Procedures.
To execute a Tcl command in Mmucl prepend the command with
whatever the character config option script_char
is set to, by default /.
Most of the time you will want to use a real editor and write
the scripts to a file. Then you can load them into Mmucl with
/source file.
On startup Mmucl loads .mmucl2/mmucl.rc if it exists.
Taken directly from the Tcl docs:
The following rules define the syntax and semantics of the Tcl language.
" then the word is terminated by the next
double-quote character. If semi-colons, close
brackets, or white space characters (including newlines)
appear between the quotes then they are treated as
ordinary characters and included in the word. Command
substitution, variable substitution, and backslash
substitution are performed on the characters between
the quotes as described below. The double-quotes are not
retained as part of the word.
{ then the word is terminated by the matching
close brace }. Braces nest within the word:
for each additional open brace there must be an
additional close brace (however, if an open brace
or close brace within the word is quoted with a
backslash then it is not counted in locating the
matching close brace). No substitutions are
performed on the characters between the braces
except for backslash-newline substitutions
described below, nor do semi-colons, newlines,
close brackets, or white space receive any special
interpretation. The word will consist of exactly
the characters between the outer braces, not
including the braces themselves.
[ then Tcl
performs command substitution. To do this it
invokes the Tcl interpreter recursively to process
the characters following the open bracket as a Tcl
script. The script may contain any number of commands
and must be terminated by a close bracket
]. The result of the script (i.e. the result
of its last command) is substituted into the word
in place of the brackets and all of the characters
between them. There may be any number of command
substitutions in a single word. Command substitution
is not performed on words enclosed in braces.
$ then Tcl
performs variable substitution: the dollar-sign
and the following characters are replaced in the
word by the value of a variable. Variable substitution
may take any of the following forms:
$name$name(index)
${name}
There may be any number of variable substitutions in a single word. Variable substitution is not performed on words enclosed in braces.
\ appears within a word then
backslash substitution occurs. In all cases but
those described below the backslash is dropped and
the following character is treated as an ordinary
character and included in the word. This allows
characters such as double quotes, close brackets,
and dollar signs to be included in words without
triggering special processing. The following table
lists the backslash sequences that are handled specially,
along with the value that replaces each sequence.
\a
\b
\f
\n
\r
\t
\v
\<newline>whitespace
\\
\.
\ooo
\xhh
\uhhhh
# appears at a point
where Tcl is expecting the first character of the
first word of a command, then the hash character
and the characters that follow it, up through the
next newline, are treated as a comment and ignored.
The comment character only has significance when it
appears at the beginning of a command.
This section gives you a crash course in using Tcl. Bear in mind that it sins by simplification. For a precise definition of Tcl's syntax see Syntax. For information on the various Tcl commands that are mentioned, consult the documentation that came with your Tcl installation.
A Tcl script consists of one or more Tcl commands. A Tcl command has the syntax:
cmd arg...
Commands are broken up into tokens. A token is simply a string. White space (spaces or tabs) seperates the tokens of a command. A command terminates with a newline or semi-colon.
The first token, cmd identifies the command to be executed. Zero or more arg tokens follow cmd. They are the arguments to that command. The command determines what the actual meanings of the arguments are.
echo hello, world
The command echo executes with two arguments, hello, and
world.
If a token begins with " or {, the token
contains all the characters up to the next " or } respectively.
This allows a token to include white space. Braces can nest,
double quotes cannot.
echo "hello, world"
The command echo executes with one argument, hello, world.
Before a command executes, Tcl performs variable, command, and backslash
substitution on the tokens making up the command. Braces, {},
prevent the substitutions from being done to the string they enclose.
Variables are created with the set command.
set foo bar
set n 32
This creates variables, foo, and n whose
values are bar, and 32 respectively.
If a token contains a $ then the token undergoes variable
substitution. Every occurence of $name in a token is replaced
with the variable name's value.
echo $foo ab$n
After substitution the command becomes echo bar ab32.
If a token contains a [ then the token undergoes command
substitution. The string beginning with [ and and ending
at the next ] is evaluated as a Tcl script and becomes the
value returned by the last command in the script. Note that in
this case if is choosing to do command substitution to it's
argument of [string length $str].
if {[string length $str]} {
echo "$str is not empty, length [string length $str]"
}
If the length of $str is not zero, report its length.
Note that the two arguments to if are enclosed by braces.
That means no substitutions are performed on them. The arguments
are simply strings. The command if chooses to evaluate the second
as a script and the first as an expression.
The special interpretation of characters like [,
$ can be escaped with \.
echo "\[string length foo\]"
This prints [string length foo] to the screen.
Scripts stop executing when an error occurs. The global variable
errorInfo is set to a stack trace of the commands leading
up to the error. Errors can be generated with the error command.
Errors can be caught with the command catch.
Example:
proc source2 {file} {
global errorInfo
if {[catch {source $file} ret]} {
echo "Error loading $file: $ret"
echo "Stack trace:"
echo $errorInfo
} else {
return $ret
}
}
The command source2 tries to source a file. If there
is an error in the file, the error along with a stack trace
is reported.
key set Print {
echo [color "Stack Trace:" bold]
echo $errorInfo
}
This creates a key binding that prints out the stack trace of the last error.
alias set annoy {
if {$1 eq ""} {
error "no target given to annoy"
}
for {set i 0} {$i < 5} {incr i} {
write "smack $1" "spit $1" "kick $1 in the groin"
}
}
Create an alias that uses annoying emotes on someone. If an argument isn't give, the alias aborts with a useful error message.
Arrays are variables that contain a set of strings. Those strings are indexed by strings. (Tcl arrays are implemented internally by hashtables).
Arrays can be created with the set command just
like normal variables.
set arg(first) 3
set arg(2) one
This creates an array arg which holds two values,
3 and one which are indexed by the strings
first and 2 respectively.
To access the value of element el of array array
use $array(el).
echo "first: $arg(first)"
echo "2: $arg(2)"
This prints out two indices of array arg and the values associated
with them.
To print out an entire array, array, you would do something like
the following:
foreach index [array names array] {
echo "$index: $array($index)"
}
A Tcl list is a string of tokens separated by white-space.
Every list is a string, but not every string is a list.
The string this is a string is a list consisting of
four elements. The string this { is not. Internally
lists in Tcl are implemented as arrays.
set nums {one two three four five six}
foreach n $nums {
foo $n
}
Starting from the first element of the list nums, every element
of the list is assigned to n and the body of the loop evaluated.
Alternately:
set nums {one two three four five six}
for {set i 0} {$i < [llength $nums]} {incr i} {
foo [lindex $nums $i]
}
but the first example is more efficient.
New Tcl commands can be created with the command proc.
proc foo {} {
echo foo!
}
This creates a command, foo, that prints foo! to the
screen. The command doesn't take any arguments.
proc lastchar {str} {
return [string index $str [expr [string length $str] - 1]]
}
This creates a command lastchar which returns the
last character of its argument.
Variables created in procedures have local scope. Variables
created outside procedures have global scope. To access
a global variable from a procedure, use the command global.
set verbose 1
proc laverage {nums} {
global verbose
if {$verbose} {
echo "procedure average called with [llength $nums] numbers"
}
set sum 0
foreach num $nums {
incr sum $num
}
return [expr {$sum / [llength $nums]}]
}
The command laverage prints out the number of arguments
given to it, if the global variable verbose is true, and
returns returns the average of the numbers in the list passed
to it.
if {$foo == "bar"} {
do something
}
use eq like so:
if {$foo eq "bar"} {
do something
}
Using eq is faster and avoids some nasty
special cases.
string commands to pick apart a string,
use regexp instead.
Loop from 0 to 9 calling the command foo
with the number of the iteration as an argument.
for {set i 0} {$i < 10} {incr i} {
foo $i
}
Alternately:
set i 0
while {$i < 10} {
foo $i
incr i
}
Compute the factorial of a number.
proc fac {n} {
for {set res 1} {$n > 1} {incr n -1} {
set res [expr {$n * $res}]
}
return $res
}
Return the unique elements of a list. The order of the elements is lost.
proc luniq {list} {
foreach el $list {
set x($l) ""
}
return [array names x]
}
Many of the commands Mmucl provides take pattern arguments. The three types of patterns, format, regexp, and glob, used are described below.
More likely than not the text you will be most interested in matching will be output from the mud.
Mmucl checks actions and subs against chunks of text sent from the mud, not line by line. (The config option action_by_line enables line by line matching for actions.) An action will be triggered a maximum of one time for a given chunk of text. A sub will replace its pattern many times in a chunk.
Actions matching occurs before the output is transformed by
the subs. If the config option strip_ansi is true,
the text checked against actions will have ANSI codes removed.
The order in which individual action are matched and individual substitutions made is dependent on the priorities of those actions and subs. Priorities are integers and actions or subs with higher priorities are guaranteed to be operated on before those with lower priority.
Types of patterns:
Special characters in a pattern denote a match. A match corresponds to a type of string, such as a number.
Matches:
%a
%c
%d
%s
%w
Like a match, an anchor is specially interpreted. An anchor forces the pattern to match some location.
Anchors:
^
$
Other characters than anchors or matches in a pattern are matched exactly.
To disable the special interpretation of a match
prepend % to it. For example, to match a
literal %d, use %%d.
Another special character is *.
It matches anything or nothing. A literal *
can be matched with **.
Finally a |, breaks the pattern into two
branches. Each branch is a pattern. If the
first branch fails to match anything, the second
will be tried. A literal | can be matched
with ||.
Literal ^ and $ can be matched with
^^ and $$ respectively.
A format pattern cannot be malformed. It may not match what you intend it to, but it will match something.
Examples:
%w is here will match dog is here, but
not big dog is here. To match the latter use
%s instead of %w.
%s is here|%s are here will match
dog is here or two dogs are here.
Note that this describes basic regular expressions not the extended ones present in new versions of Tcl. Read the documentation that comes with Tcl for a complete explanation.
From the Tcl docs:
A regular expression is zero or more branches, separated
by |. It matches anything that matches one of the
branches.
A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.
A piece is an atom possibly followed by *, +, or
?. An atom followed by * matches a sequence of 0
or more matches of the atom. An atom followed by +
matches a sequence of 1 or more matches of the atom. An
atom followed by ? matches a match of the atom, or the
null string.
An atom is a regular expression in parentheses (matching a
match for the regular expression), a range (see below),
. (matching any single character), ^ (matching
the null string at the beginning of the input string),
$ (matching the null string at the end of the input
string), a \ followed by a single character (matching
that character), or a single character with no other
significance (matching that character).
A range is a sequence of characters enclosed in [].
It normally matches any single character from the
sequence. If the sequence begins with ^, it matches
any single character not from the rest of the sequence.
If two characters in the sequence are separated by -,
this is shorthand for the full list of ASCII characters
between them (e.g. [0-9] matches any decimal digit).
To include a literal ] in the sequence, make it the
first character (following a possible ^). To include
a literal -, make it the first or last character.
Examples:
[0-9]+ matches an unsigned integer.
\-?[0-9]+ would match a signed integer.
[][\*\(\)\$\^\+\.\?\|\\] matches a special
character in a basic regular expression.
Note that some of the special characters in a
regexp like [ or $ need to be
hidden from the Tcl parser. To avoid
quoting hell, try to put your regexps in {}.
This is the same type of matching used by Tcl's string match
command.
From the Tcl docs:
For the two strings to match, their contents must be identical except that the following special sequences may appear in pattern:
*
?
[chars]
\x
*?[]\ in pattern.
Examples:
test* matches anything beginning with test.
\* matches *.
These are commands that Mmucl makes available to the user.
The following shorthand is used to describe the syntax of the commands. Each argument is one of:
[name]
[name value]
[-switch value -switch --]
- and ending with -- or an argument that
doesn't begin with -. Some switches take arguments
...
Commands defined by Mmucl:
An action consists of a format pattern and a script. When the pattern matches output from the mud, the script is evaluated. The script has global scope. See Patterns, for information on pattern matching.
Usage: action option arg...
Options:
set [-group group -priority priority -type --] pattern [script]
format, exact, or regexp. The default is
format. The priority switch determines the order in which
actions are matched and must be an integer. Higher priority actions
are matched first.
If not, return the script associated with pattern.
names [-group group --] [glob *]
delete [-group group -exact --] glob-exact switch forces literal string matching of glob.
print [-group group --] [glob *]
priority [-group group --] pattern [? priority]
match [-group group --] str [glob *]
state [-group group --]
The switch group always defaults to default. See group,
for more information.
The script has these global variables available to it:
1-9
%, counting from the left,
in the action's pattern.
0
Examples:
action set {^%w tells you:} {
write "tell $1 I'm afk. brb"
bell
}
Whenever you get a tell, reply that you are afk and ring a bell.
action print *bob*
Print out all the actions with bob somewhere in their
pattern.
action set {^Hp: %d(%d)} {
set status(hp) $1
set status(max_hp) $2
}
Keep hp and max_hp in the global array status updated for use in other scripts.
action set {^%w grins|^%w bows} {
write "smack $1$2"
}
Whenever someone grins or bows, smack them!
An alias consists of a name and a script. When the first word, a block of anything not whitespace, of input matches an alias name, the script is evaluated.
Usage: alias option arg...
Options:
set [-group group --] name [script]
names [-group group --] [glob *]
delete [-group group -exact --] glob-exact switch forces exact string matching.
print [-group group --] [glob *]
state [-group group --]
The switch group always defaults to default. See group,
for more information.
The script has these global variables available to it:
0
1-3
Examples:
alias set k {write "kill $0"}
Send kill followed by any arguments to the mud every
time k is typed.
alias delete *
Delete all the defined aliases.
alias delete -exact *
Delete the alias *.
alias set sneak {
set dirs {n e w s ne nw se sw}
if {$1} {
foreach dir $dirs {
alias set $dir [list write "sneak $dir"]
}
} else {
foreach dir $dirs {
alias delete -exact -- $dir
}
}
}
Set or delete aliases for directions that send "sneak direction" to the mud.
alias set r {
if {![regexp {^\s*(.*?)\s*(\d+)$} $0 x str num]} {
set str $0
set num 1
}
for {set i 0} {$i < $num} {incr i} {
write $str
}
}
Find a number at the end of the argument string. Write everything up to that number, except buffering white-space, to the mud that number times.
Ring a bell.
Usage: bell
Examples:
key set Control-g bell
Ring the bell every time Control-g is pressed.
A char stores information about a character on a mud.
Mmucl saves the information on exit and restores it
on startup. Each character has an init file in ~/.mmucl2/chars.
Usage: char option arg...
Options:
set name [info]
If info is given, define a character.
An init file, name, will be created in
~/.mmucl2/chars.
Otherwise return the info associated with name.
names [glob *]
delete -- glob-exact switch forces exact string matching.
print [glob *]
load nameExamples:
char set Arithon {dracos.ptn.net 3000 {arithon passwd}}
On connection to the mud, arithon and then passwd
will be sent. You may want to make sure ~/.mmucl2 where
the character information is stored readable only by you.
The login list is stored as plain text.
char set Arithon {dracos.ptn.net 3000}
Just like the above except nothing in sent to the mud on connect.
Do argument handling for a procedure.
Usage: check [-opts --] name syntax arglist
If the switch -opts is given, then the command has
options (subcommands) and syntax is a list of the
form {(option spec)...}.
Otherwise syntax is a list of the form
{spec}.
Each spec indicates a type of argument the command takes and is a list of the form:
{+ name}
{? name}
{? name default}
{- name {name2 value}...}
The arguments are checked against syntax and check aborts with an appropriate error message if they do not match the syntax.
If the syntax of the arguments is correct, the
arguments are made available to the calling block
of code in the array arg indexed by name.
Switches will be 1 if given, and 0 if not.
Examples:
proc rand {args} {
set syntax {
seed {{? seed}}
get_int {{+ range} {? min 0} }
get_float {{+ range} {? min 0}}
}
switch -exact -- [check -opts rand $syntax $args] {
seed {
if {[info exists arg(seed)]} {
expr {srand($arg(seed))}
} else {
expr {srand([clock clicks])}
}
} get_int {
return [expr {int(rand() * $arg(range)) + $arg(min)}]
} get_float {
return [expr {rand() * $arg(range) + $arg(min)}]
}
}
return
}
This creates a command rand that has subcommands,
seed, get_int, and get_float.
Modify the current command line. Only the graphical interfaces completely implement this function.
Usage: cline option arg...
Options:
delete [index1 0] [index2 end]
get [index1 0] [index2 end]
insert index stringhistory
hist_keep commands
typed.
hide [bool 1]
Index:
n
insert
end
Examples:
key set Control-u {cline delete 0 insert}
Delete the current line when Control-x is hit.
Return a string with ansi text attributes.
Usage: color (str attribs)...
Colors: black, red, green, yellow, brown, blue, magenta, cyan, and white.
All of the text attributes below and the colors listed above may or may not be supported by whatever console the text is displayed in.
The argument attribs is a list made up of these text attributes:
reset
bold
dim
underline
blink
reverse
bg_colorThe string returned will always end with the attributes
given by the config option end_color.
Examples:
echo [color WARNING!! {bold red}]
Display "WARNING!!" in bold font with a red foreground.
color r red a green i yellow n blue b white o cyan w magenta
Return rainbow with ansi codes to set each character
to a different color.
Change and inspect Mmucl config options.
Usage: config option arg...
Options:
set option [value]
names [glob *]
print [glob]
state
reset
Options
action_by_line
actions
echo
echo_color
error_color
hist_keep
hist_min
keep_line
print_color
report_color
reconnect
script_char
split_char
strip_ansi
subs
timeout
use_mccp
use_threads
verbatim_char
Examples:
config print *_color
Print out all the config options that set a color.
config set script_char #
Scripts typed at the command line now must begin with #.
Connect to a mud.
Usage: connect host port [login {}]
Connect to host at port. Each element of the list
login is written to the mud on a successful connection. The config
option timeout determines how long connect waits for
a response. If the connection attempt times out, Mmucl will try
reconnecting the number of times the config option reconnect
is set to.
Examples:
connect mud.domain 2000 {name passwd 1}
Try to connect to the mud running at mud.domain on port 2000.
If we connect write name, passwd, and then 1
to the mud.
connect dracos.ptn.net 3000
Try to connect to the mud running at dracos.ptn.net on port 3000.
Disconnect ends a connection to a mud and will also stop an attempted connection.
Usage: disconnect
Examples:
key set Escape disconnect
Set up a key binding to disconnect.
The command dump can save to a file the data created by the
commands action, alias,
char, config, key, and sub. Procedures
and variables can also be saved.
The data can then be recreated by loading the file produced with
the command source.
Syntax: dump -- file
Switches:
-cmd-group valuedefault.
See group, for more info.
-append
-proc
-var
By default everything is dumped.
Examples:
dump -alias -- aliases
Write all the currently defined aliases to the file aliases.
proc exit_save {} {
dump -- [file join [mmucl rc_dir] save]
exit
}
Create a command save_exit that saves everything to the
file ~/.mmucl2/save and then exits.
On startup you could load everything back in
with by putting source [file join $env(HOME) .mmucl2 save]
in your mmucl.rc.
Write to the display.
Usage echo str...
Echo joins all the str's into a single string with a space inbetween each str, appends a newline to the end, and writes the result to the display.
Examples:
echo "foo bar"
echo foo bar
The result is the same for each echo.
echo [color "It's Christmas!" {bold red bg_green}]
Print "It's Christmas" in bold red with a green background.
proc minfo {} {
global env tcl_platform tcl_version tk_version
echo "Host: [info hostname]"
echo "OS: $tcl_platform(os) $tcl_platform(osVersion)"
echo "Tcl version: $tcl_version"
catch {echo "Tk version: $tk_version"}
echo "Home directory: $env(HOME)"
echo
echo Aliases: [llength [alias names]]
echo Actions: [llength [action names]]
echo Subs: [llength [sub names]]
echo Keys: [llength [key names]]
echo Chars: [llength [char names]]
}
Define a command minfo that print out miscellaneous info about
the system Mmucl is running on and the user interp.
Log on to that strange place known as real life.
Usage: exit
Exit also saves any chars defined as well as all the config options so that they can be restored on startup.
A group is a set of aliases, actions, keys, and subs that can be
manipulated as one unit. Groups can be created, and there members
manipulated, by using one of the
above type set commands and passing in -group name.
The default group, default, cannot be deleted. Deleting
default will clear the group. Members in a group can
have the same name as the equivalent type in another group. For
example if two aliases in different groups share the same name, that
name will trigger the evaluation of both aliases.
Usage: group option arg...
Options:
names [glob *]
delete -- glob-exact switch forces exact string matching.
print [glob *]
Examples:
key set -group capture Key {
append mud_text [cline get]
}
action set -group capture * {
append mud_text $0
}
Creates a capture group with two members that append all mud
output and user input to the end of the global variable
mud_text. By putting these in their own group we can define
other actions and keys with the same pattern or key event in other
groups and have all of them be triggered as appropriate.
Start an info browser to read Mmucl's info file.
Usage: help [subject]
If subject is given go to node subject. Otherwise go to the Top node. Note that this may be an empty stub in some interfaces.
Examples:
help help
Go to this node.
A key consists of an event and a script. When a sequence of keys matches an event, the script is evaluated. The script has global scope. Note that this may be an empty stub in the text interfaces.
Much of the information in this section was taken
from the Tk documentation on the command bind.
Usage: key option arg...
Options:
set [-group group --] key [script]
names [-group group --] [glob *]
delete [-group group --] -- [glob *]
-exact switch forces literal string matching of glob.
print [-group group --] [glob *]
current
state [-group group --]
The switch group always defaults to default.See group,
for more information.
Key events describe a sequence of key presses.
Each event pattern may take one of two forms.
In the simplest case it is a single printing ASCII character,
such as a or [. The character may not be a space
character or the character <. This form of pattern
matches a key press for the particular character.
The second form of pattern is modifier-keysym.
This form of pattern matches a key being hit, the keysym, while
another is being held, the modifier. There may be more than one modifier
separated by -.
Modifiers:
Control
Shift
Alt
Modx1 to 5.
Keysyms are textual specifications for particular keys on the
keyboard; they include all the alphanumeric ASCII characters
(e.g. a is the keysym for the ASCII character a), plus
descriptions for non-alphanumeric characters (comma is the
keysym for the comma character), plus descriptions for all the
non-ASCII keys on the keyboard (Shift_L is the keysym for the
left shift key, and F1 is the keysym for the F1 function
key, if it exists). The complete list of keysyms may vary from system
to system and from interface to interface. The special keysym
Key matches any key being pressed. As shown below, it can be
used with key current to see all the keysyms available.
User defined key bindings are checked before system bindings. (This is
an ideal and may not be completely true across different platforms and
interfaces.) The system key bindings control aspects of the interface
such as opening dialog boxes and may vary from interface to
interface. To prevent a system binding that matches a user binding
from also executing, use the break comand to terminate the
script.
Examples:
key set Key {echo [key current]}
Print out key events as they occur.
key set Escape {write flee}
Send "flee" to the mud when Escape is hit.
key set a break
Prevent the key a from causing a to be inserted in the input entry.
Now how do you about removing this key binding?
Query various information about the client.
Usage: mmucl option arg...
Options:
lib_dir
rc_dir
host
port
version
connect
interface
Examples:
glob --nocomplain -directory [file join [mmucl rc_dir] chars] *
Get a list of all the character config files.
Interpret a string just as if you'd typed it in.
Usage: parse str
If str begins with the config option verbatim_char,
by default \, send str, minus verbatim_char,
to the mud.
If str begines with the config option script_char,
by default /, str, minus script_char, is
evaluated as a Tcl script.
Barring the first two cases, str is split up into a sequence of
substringss delimited by the config option split_char, by default
;. If the first word of a substring matches
an alias, the alias is executed. Otherwise the substring is sent to the
mud.
Examples:
alias set . {
parse [lindex [cline history] end]
}
Reparse the last command added to history.
This is too simplistic. If . was
added to the history list, using it again
would cause an infinite loop!
proc al {name cmd} {
alias set $name [list parse $cmd]
}
Define a new command al that creates
an alias name. When invoked name acts
as if cmd had been typed instead.
Attempt to resume the last connection.
Usage: reconnect
If a login was given on the last connect, it will be sent again.
Examples:
key set F12 reconnect
Try to reconnect every time F12 is pressed.
A session is the environment all interaction with Mmucl occurs
through. That environment encapsulates all user defined data such as
procedures, variables, aliases, and actions. There are a few
exception. Config options and characters are shared between all sessions.
Sessions can communicate only through session eval.
Starting Mmucl automatically creates a default session. New sessions can
be created with session new. Each session has a numerical id with
which it can be manipulated. Only one session is current at a given
time. That session receives all user input and typically, unless
snooped, only output from that session is displayed. The current session may be
changed with session switch.
The primary purpose of sessions is to allow playing several muds simultaneously. Each session can be connected to one mud.
Usage: session option arg...
Options:
new
names
eval id scriptswitch idsnoop id [bool true]
current
close idprint
A sub consists of a format pattern and a subspec. The sub replaces every occurence of its pattern in mud output with its subspec. See Patterns, for information on pattern matching.
Usage: sub option arg...
Options:
set [-group group -priority priority -type --]
If subspec is given create a sub. The switch type
indicates what kind of pattern is being set and must be one of
format, exact, or regexp. The default is
format. The priority switch determines the order in which
subs are matched and must be an integer. Higher priority actions
are matched first.
If not, return the subspec associated with pattern.
names [-group group --] [glob *]
delete [-group group -exact --] glob-exact forces literal string
matching of glob.
print [-group group --] [glob *]
priority [-group group --] pattern [? priority]
match [-group group --] str [glob *]
state [-group group --]
While replacing a pattern with a subspec the following substitutions in subspec are done:
\n
\0
&
\\
\&
If the subsepc has backslashes, you'll like want to protect
it from Tcl's interpretation of backslashes by putting
it in braces, {}.
Examples:
sub set "^%w tells you: %s" {"\2", says \1}
Change Renir tells you: heheh to "heheh", says Renir.
sub set Arithon [color & {bold magenta}]
Change Arithon's color to be bold magenta.
proc gag {name} {
sub set -group gag -- ^%s$name%s ""
}
proc ungag {name} {
sub delete -group gag -exact -- ^%s$name%s
}
Define two commands, gag and ungag that
respectively set a gag on name, deleting
every line with name in it, or remove a
gag on name. This isn't completely correct.
completely correct. To make sure you match name,
you'd have to escape any format patterns in name.
Send a file to the mud.
Usage: textin file
Textin writes file to the mud.
Examples:
alias set postfile {
write "post file: $1"
textin $1
write .
}
Create an alias postfile that, on
RoD anyway, posts a file to a message board.
Send strings to the mud.
Usage: write str...
Send each str to the mud.
Examples:
write "get all from corpses"
write "bury all"
The above is the same as:
write "get all from corpses" "bury all"
Aliases scripts have global scope. Variables created
in an alias are global, but variables created in a procedure are by
default local. For more information
see the Tcl docs on global and namespace.
set gvar test
alias set foo {
echo $gvar
}
The alias prints out test.
proc foo {} {
global gvar
set gvar test2
return $gvar
}
The procedure sets and returns the value of the global variable gvar.
Follow the directions in the file INSTALL.
You have to insert ansi codes to do the colors with a sub. A string with ansi colors can be created with the color command.
proc highlight {format colors} {
sub set $format [color & $colors]
}
This highlight procedure will add a list of colors a the format pattern. Read about the color command to see what text attributes are supported.
Not builtin, but it can be added easily. Look at the sample mmucl.rc for one implementation.
You have to use the key command to bind scripts to the keypad. Look at the move command in the sample mmucl.rc for an example.
Keys may do other things than just what you bind them to. To prevent a key from doing anything but what its bound to, have the script break.
key set a break
This prevents a from appearing in the input widget when the key a is hit.
key set KP_Add {write up; break}
Send "up" to the mud when the plus in the keypad is hit and don't print a plus on the input entry.
Remember you are matching a chunk of text. The beginning of a line is either preceded by a newline or by nothing.
rxp_action set "(^|\n)Beg of a line" {echo Whee!}
If you are in action_by_line mode then just "^Beg of a line" will work.
Alternately enable -line mode in the regexp with
(?n)^Beg of line.
If you have comments, ideas, or suggestions, I'd be interested in hearing them. Bear in mind that I'm only interested in adding features that cannot be implemented in the user interp. Take a look through the manual to see if Mmucl already provides the functionality to implement what you want.
For bug reports I need to know your Mmucl version, Tcl/Tk version, operating system, and, if relevant, the address of the mud you are having a problem on.
Mail feedback to msp@users.sourceforge.net and please
put Mmucl somewhere on the subject line.
Alternately fill out a bug report on the Sourceforge
project page, http://sourceforge.net/projects/mmucl