This is mmucl.info, produced by makeinfo version 4.0 from mmucl.texinfo.

   Mmucl Manual Copyright (C) 1998-1999 Mark Patton

INFO-DIR-SECTION Miscellaneous
START-INFO-DIR-ENTRY
* Mmucl: (mmucl).       Mark's MUd CLient
END-INFO-DIR-ENTRY


File: mmucl.info,  Node: Top,  Next: About,  Up: (dir)

Mark's Mud Client Manual
************************

   Mmucl (pronounced muckle) is a mud client written in Tcl.

* Menu:

* About::        Version and author info.
* Copying::      Your rights.
* Overview::     What is Mmucl?
* Tutorial::     A quickstart.
* Scripts::      Using Tcl.
* Patterns::     Matching text.
* Procedures::   Procedures Mmucl defines.
* Feedback::     Reporting a bug.


File: mmucl.info,  Node: About,  Next: Copying,  Prev: Top,  Up: Top

About
*****

   Mmucl is maintained by Mark Patton, <msp@users.sourceforge.net>.

   The current stable version of Mmucl, with which this manual was
distributed, is 1.4.1.

   You can find the latest news at the Mmucl home page,
`http://mmucl.sourceforge.net'.


File: mmucl.info,  Node: Copying,  Next: Overview,  Prev: About,  Up: Top

Copying
*******

   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.


File: mmucl.info,  Node: Overview,  Next: Tutorial,  Prev: Copying,  Up: Top

Overview
********

   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, and
macros to name a few. Mmucl's most powerful feature is its
extensibility through Tcl scripts. *Note Scripts::, for more info.


File: mmucl.info,  Node: Tutorial,  Next: Scripts,  Prev: Overview,  Up: Top

Tutorial
********

   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 *Note 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 *Note alias::.

   For a more exact description of command line interpretation, see
*Note 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. *Note
key::, for more about binding keys.

     key set <Key-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 {![string equal $1 ""]} {
             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. *Note 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.) *Note
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"
     }


File: mmucl.info,  Node: Scripts,  Next: Patterns,  Prev: Tutorial,  Up: Top

Scripts
*******

   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. *Note
Procedures::.

   To execute a Tcl command in Mmucl prepend the command with whatever
the character config option `script_char' is set to, probably `/'.

   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 `.mmucl/mmucl.rc' if it exists.

* Menu:

* Syntax::
* Basics::
* Errors::
* Arrays::
* Lists::
* New commands::
* Tips::
* Examples::


File: mmucl.info,  Node: Syntax,  Next: Basics,  Up: Scripts

Syntax
======

   Taken directly from the Tcl docs:

   The following rules define the syntax and semantics of the Tcl
language.

  1. A Tcl script is a string containing one or more commands.
     Semi-colons and newlines are command separators unless quoted as
     described below. Close brackets are command terminators during
     command substitution (see below) unless quoted.

  2. A command is evaluated in two steps. First, the Tcl interpreter
     breaks the command into words and performs substitutions as
     described below. These substitutions are performed in the same way
     for all commands. The first word is used to locate a command
     procedure to carry out the command, then all of the words of the
     command are passed to the command procedure. The command procedure
     is free to interpret each of its words in any way it likes, such
     as an integer, variable name, list, or Tcl script. Different
     commands interpret their words differently.

  3. Words of a command are separated by white space (except for
     newlines, which are command separators).

  4. If the first character of a word is double-quote `"' 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.

  5. If the first character of a word is an open brace `{' 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.

  6. If a word contains an open bracket `[' 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.

  7. If a word contains a dollar-sign `$' 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 is the name of a scalar variable; the name is terminated
          by any character that isn't a letter, digit, or underscore.

    `$NAME(INDEX)'
          NAME gives the name of an array variable and INDEX gives the
          name of an element within that array. NAME must contain only
          letters, digits, and underscores. Command substitutions,
          variable substitutions, and backslash substitutions are
          performed on the characters of index.

    `${NAME}'
          NAME is the name of a scalar variable. It may contain any
          characters whatsoever except for close braces.

     There may be any number of variable substitutions in a single
     word. Variable substitution is not performed on words enclosed in
     braces.

  8. If a backslash `\' 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'
          Audible alert (bell) (0x7).

    `\b'
          Backspace (0x8).

    `\f'
          Form feed (0xc).

    `\n'
          Newline (0xa).

    `\r'
          Carriage-return (0xd).

    `\t'
          Tab (0x9).

    `\v'
          Vertical tab (0xb).

    `\<newline>whitespace'
          A single space character replaces the backslash, newline, and
          all spaces and tabs after the newline. This backslash sequence
          is unique in that it is replaced in a separate pre-pass
          before the command is actually parsed. This means that it
          will be replaced even when it occurs between braces, and the
          resulting space will be treated as a word separator if it
          isn't in braces or quotes.

    `\\'
          Backslash `\'.

    `\ooo'
          The digits ooo (one, two, or three of them) give an eight-bit
          octal value for the Unicode character that will be inserted.
          The upper bits of the Unicode character will be 0.

    `\xhh'
          The hexadecimal digits hh give an eight-bit hexadecimal value
          for the Unicode character that will be inserted. Any number of
          hexadecimal digits may be present; however, all but the last
          two are ignored (the result is always a one-byte quantity).
          The upper bits of the Unicode character will be 0.

    `\uhhhh'
          The  hexadecimal digits hhhh (one, two, three, or four of
          them) give a sixteen-bit hexadecimal value for the Unicode
          character that will be inserted. Backslash substitution is
          not performed on words enclosed in braces, except for
          backslash-newline as described above.

  9. If a hash character `#' 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.

 10. Each character is processed exactly once by the Tcl interpreter as
     part of creating the words of a command.  For example, if variable
     substitution occurs then no further substitutions are performed on
     the value of the variable; the value is inserted into the word
     verbatim. If command substitution occurs then the nested command
     is processed entirely by the recursive call to the Tcl
     interpreter; no substitutions are performed before making the
     recursive call and no additional substitutions are performed on
     the result of the nested script.

 11. Substitutions do not affect the word boundaries of a command. For
     example, during variable substitution the entire value of the
     variable becomes part of a single word, even if the variable's
     value contains spaces.


File: mmucl.info,  Node: Basics,  Next: Errors,  Prev: Syntax,  Up: Scripts

Basics
======

   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 *Note 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.

     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.


File: mmucl.info,  Node: Errors,  Next: Arrays,  Prev: Basics,  Up: Scripts

Errors
======

   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 {[string equal $0 ""] == 0} {
             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.


File: mmucl.info,  Node: Arrays,  Next: Lists,  Prev: Errors,  Up: Scripts

Arrays
======

   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)"
     }


File: mmucl.info,  Node: Lists,  Next: New commands,  Prev: Arrays,  Up: Scripts

Lists
=====

   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.

     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.


File: mmucl.info,  Node: New commands,  Next: Tips,  Prev: Lists,  Up: Scripts

New commands
============

   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.


File: mmucl.info,  Node: Tips,  Next: Examples,  Prev: New commands,  Up: Scripts

Tips
====

  1. To test string equality do not use:

          if {$foo == "bar"} {
              do something
          }

     use `string equal' like so:

          if {[string equal $foo "bar"]} {
              do something
          }

     Using `string equal' is faster and avoids some nasty special cases.

  2. If you find yourself using more than a couple `string' commands to
     pick apart a string, use `regexp' instead.

  3. Use arrays to group related global variables together.

  4. For the most part treat lists as lists, strings as strings, and
     numbers as numbers. Not doing so can often lead to subtle bugs.


File: mmucl.info,  Node: Examples,  Prev: Tips,  Up: Scripts

Examples
========

   Loop from 0 to 9 calling the command `foo' with the number of the
iteraton 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]
     }


File: mmucl.info,  Node: Patterns,  Next: Procedures,  Prev: Scripts,  Up: Top

Patterns
********

   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 ubs against chunks of text sent from the
mud, not line by line. (The config option action_by_line enables line
by line matching.) 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.

   Types of patterns:

* Menu:

* Format::   looks like scanf format
* Regexp::   regular expressions
* Glob::     glob matching


File: mmucl.info,  Node: Format,  Next: Regexp,  Up: Patterns

Format
======

   Special characters in a pattern denote a "match".  A "match"
corresponds to a type of string, such as a number.

   Matches:

`%a'
     An ANSI color code.

`%c'
     One character.

`%d'
     A number.

`%s'
     Anything up to the end of a line.

`%w'
     A "word", a contiguous block of anything that isn't whitespace.

   Like a match, an "anchor" is specially interpreted.  An "anchor"
forces the pattern to match some location.

   Anchors:

`^'
     The beginning of a line.

`$'
     The end of a line.

   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'.


File: mmucl.info,  Node: Regexp,  Next: Glob,  Prev: Format,  Up: Patterns

Regexp
======

   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 `{}'.


File: mmucl.info,  Node: Glob,  Prev: Regexp,  Up: Patterns

Glob
====

   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:

`*'
     Matches any sequence  of  characters in string, including a null
     string.

`?'
     Matches any single character in string.

`[chars]'
     Matches any character in the set given by chars. If a sequence  of
     the form x-y appears in chars, then any character between x and y,
     inclusive, will match.

`\x'
     Matches the single character x.  This provides a way of avoiding
     the special interpretation of the characters `*?[]\' in pattern.

   Examples:

   `test*' matches anything beginning with `test'.

   `\*' matches `*'.


File: mmucl.info,  Node: Procedures,  Next: Feedback,  Prev: Patterns,  Up: Top

Procedures
**********

   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'
     The argument NAME must be given.

`[NAME]'
     The argument NAME is optional.

`[NAME VALUE]'
     If NAME is not given, the command treats NAME as if it had been
     given as VALUE.

`--'
     Indicates the command accepts switches.  Switches consist of zero
     or more arguments preceded by `-' and ending with `--' or an
     argument that doesn't begin with `-'.

`NAME...'
     The argument NAME can occur zero or more times.

   Commands defined by Mmucl:

* Menu:

* action::       Automatically respond to mud output.
* alias::        Shortcuts to Tcl scripts.
* bell::         Ring a bell.
* char::         Manipulate characters.
* check::        Enforce a given syntax on a command.
* cline::        Modify and inspect the command line.
* color::        Create strings with ANSI codes.
* config::       Configure various aspects of Mmucl
* connect::      Connect to a mud.
* disconnect::   Disconnect from a mud.
* dump::         Save client state to a file.
* echo::         Write to the display.
* exit::         Quit Mmucl.
* help::         Look at this manual.
* key::          Bind scripts to keys.
* mmucl::        Query client status.
* parse::        Simulate the command line.
* reconnect::    Connect to the last mud connected to.
* sub::          Transform mud output.
* textin::       Read a file into the mud.
* write::        Send strings to the mud.


File: mmucl.info,  Node: action,  Next: alias,  Up: Procedures

action
======

   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 local scope. The command `rxp_action' is identical to
`action' except that `rxp_action' uses regular expressions. *Note
Patterns::, for information on pattern matching.

   Usage: `action option arg...'

   Options:

`set FORMAT [SCRIPT]'
     If SCRIPT is given create an action.  If not, return the script
     associated with FORMAT.

`names [GLOB *]'
     Return all the action patterns that match GLOB.

`delete -- GLOB'
     Delete all the actions that match GLOB.  The `-exact' switch
     forces literal string matching of GLOB.

`print [GLOB *]'
     Print to the display all the actions that match GLOB.

   The script has these local variables available to it:

`1-9'
     The nth match (only those that start with `%', counting from the
     left, in the action's pattern.

`0'
     The entire string that matched the pattern.

   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)} {
         global status
     
         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!


File: mmucl.info,  Node: alias,  Next: bell,  Prev: action,  Up: Procedures

alias
=====

   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 NAME [SCRIPT]'
     If SCRIPT is given create an alias If SCRIPT isn't given, return
     the SCRIPT associated with NAME.

`names [GLOB *]'
     Return all the alias names that match GLOB

`delete -- GLOB'
     Delete all the aliases that match GLOB.  The `-exact' switch
     forces exact string matching.

`print [GLOB *]'
     Print to the display all the aliases that match GLOB.

   The script has these local variables available to it:

`0'
     The argument string given to the alias.

`1-3'
     The first three words of the argument string.

   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 {
         regexp {^\ *(.*)\ *([0-9]+)$} $0 x str num
     
         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.


File: mmucl.info,  Node: bell,  Next: char,  Prev: alias,  Up: Procedures

bell
====

   Ring a bell.

   Usage: `bell'

   Examples:

     key set <Control-g> bell

   Ring the bell every time `Control-g' is pressed.


File: mmucl.info,  Node: char,  Next: check,  Prev: bell,  Up: Procedures

char
====

   A char stores information about a character on a mud.  Mmucl saves
the information on exit and restores it on startup.

   Usage: `char option arg...'

   Options:

`set NAME [INFO]'
     The argument INFO is a list of the form {HOST PORT LOGIN}.  The
     element LOGIN s itself a list and need not be present.

     If INFO is given, define a character.  An init file, NAME, will be
     created in `~/.mmucl/chars'.  Otherwise return the INFO associated
     with NAME.

`names [GLOB *]'
     Return all the char names that match GLOB

`delete -- GLOB'
     Delete all the chars that match GLOB.  The `-exact' switch forces
     exact string matching.

`print [GLOB *]'
     Print to the display all the chars that match GLOB.

`load NAME'
     Connect to NAME's mud, load NAME's init file, and write each
     element of LOGIN to the mud.

   Examples:

     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 `~/.mmucl' 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.


File: mmucl.info,  Node: check,  Next: cline,  Prev: char,  Up: Procedures

check
=====

   Do argument handling for a procedure.

   Usage: `check -- 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}'
     The argument NAME must be given.

`{? NAME}'
     The argument NAME is optional.

`{? NAME DEFAULT}'
     The argument NAME is optional and becomes DEFAULT if not given.

`{- NAME...}'
     The command takes switches given by NAME.

   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'.


File: mmucl.info,  Node: cline,  Next: color,  Prev: check,  Up: Procedures

cline
=====

   Modify the current command line.

   Usage: `cline option arg...'

   Options:

`delete [INDEX1 0] [INDEX2 end]'
     Delete the text from INDEX1 to INDEX2.

`get [INDEX1 0] [INDEX2 end]'
     Return the command line from INDEX1 to INDEX2.

`insert INDEX STRING'
     Insert STRING into the command line at INDEX.

`history'
     Return a list of the last config option `hist_keep' commands typed.

`hide [BOOL 1]'
     Toggle hiding command line input.

   Index:

`n'
     The nth character.

`insert'
     The location of the insertion cursor.

`end'
     The last character.

   Examples:

     bind <Control-x> {cline delete}

   Delete the current line when `Control-x' is hit.


File: mmucl.info,  Node: color,  Next: config,  Prev: cline,  Up: Procedures

color
=====

   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'
     Reset the terminal to its defaults.

`bold'
     Bold font.

`dim'
     Make the text dim.

`underline'
     Underline the text.

`blink'
     Flash the text.

`reverse'
     Reverse foreground and background

`COLOR'
     Set the foreground to one of the colors listed above.

`bg_COLOR'
     Set the background to one of the colors listed above.

   The 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.


File: mmucl.info,  Node: config,  Next: connect,  Prev: color,  Up: Procedures

config
======

   Change and inspect Mmucl config options.

   Usage: `config option arg...'

   Options:

`set OPTION [VALUE]'
     If OPTION is given, set OPTION to VALUE.  Otherwise return
     OPTION's value.

`names [GLOB *]'
     Return all the options that match GLOB

`print [GLOB]'
     Print to the display all the options that match GLOB.

   Options

`action_by_line'
     If true, check actions against every line of text.  Otherwise,
     check actions against every chunk of text.

`actions'
     Check actions?

`echo'
     Echo command line?

`echo_color'
     A list of text attributes applied to echos of the command line.

`end_color'
     Strings generated by the command `color' are always terminated
     with these text attributes.

`error_color'
     List of text attributes applied to error messages.

`hist_keep'
     Number of commands kept in history.

`hist_min'
     Minimum length of input to be stored in history.

`keep_line'
     Delete the command line after enter?

`report_color'
     List of text attribues applied to events reported by Mmucl.

`print_color'
     List of text attribues applied to text printed by Mmucl.

`reconnect'
     Number of times to try connecting to a host after timeouts.

`split_char'
     Character command line input is split on.

`script_char'
     Character at beginning of input that indicates the rest of the
     line is a Tcl script.

`strip_ansi'
     Strip out ansi codes?  (This only occurs for action matching.)

`subs'
     Check subs?

`timeout'
     Number of seconds to wait for a connection.

`verbatim_char'
     Character at beginning of input that indicates the rest of the
     line should be sent to the mud as is.

   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 `#'.


File: mmucl.info,  Node: connect,  Next: disconnect,  Prev: config,  Up: Procedures

connect
=======

   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.


File: mmucl.info,  Node: disconnect,  Next: dump,  Prev: connect,  Up: Procedures

disconnect
==========

   Disconnect ends a connection to a mud and will also stop an
attempted connection.

   Usage: `disconnect'

   Examples:

     key set <Control-q> disconnect

   Set up a key binding to disconnect.


File: mmucl.info,  Node: dump,  Next: echo,  Prev: disconnect,  Up: Procedures

dump
====

   The command `dump' can save to a file the data created by the
commands `action', `rxp_action', `alias', `char', `config', `key',
`sub', and `rxp_sub'.  The data can then be recreated by loading the
file produced with the command `source'.

   Syntax: `dump -- FILE'

   Switches:

`-CMD'
     Select CMD to save.

`-all'
     Select all the commands.

`-append'
     Write to the end of FILE

   Examples:

     dump -alias -- aliases

   Write all the currently defined aliases to the file `aliases'.

     proc exit_save {} {
         dump -all -- [file join [mmucl rc_dir] save]
         exit
     }

   Create a command `save_exit' that saves everything to the file
`~/.mmucl/save' and then exits.  On startup you could load everything
back in with by putting `source [file join $env(HOME) .mmucl save]' in
your `mmucl.rc'.


File: mmucl.info,  Node: echo,  Next: exit,  Prev: dump,  Up: Procedures

echo
====

   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.


File: mmucl.info,  Node: exit,  Next: help,  Prev: echo,  Up: Procedures

exit
====

   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.


File: mmucl.info,  Node: help,  Next: key,  Prev: exit,  Up: Procedures

help
====

   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.

   Examples:

     help help

   Go to this node.


File: mmucl.info,  Node: key,  Next: mmucl,  Prev: help,  Up: Procedures

key
===

   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.

   Much of the information in this section was taken from the Tcl
documentation on the command `bind'.

   Usage: `key option arg...'

   Options:

`set KEY [SCRIPT]'
     If SCRIPT is given, create a key.  Otherwise return the script
     bound to KEY.

`names [GLOB *]'
     Return all the key names that match GLOB

`delete -- [GLOB *]'
     Delete all the keys that match GLOB.  The `-exact' switch forces
     literal string matching of GLOB.

`print [GLOB *]'
     Print to the display all the keys that match GLOB.

   Key events:

   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 longer but more general. It has the
following syntax: `<Key-modifier-keysym>'.  The beginning `Key' is
optional and will be automatically added if not present. The entire
event pattern is surrounded by angle brackets. Inside the angle
brackets are zero or more modifiers, and a keysym.

   Modifiers:

`Control'
     Either the left or right control key, keysyms Control_L and
     Control_R.

`Shift'
     Either the left or right shift key, keysyms Shift_L and Shift_R.

`Alt'
     Either the left of right alt key, keysyms Alt_L and Alt_R

`Double'
     Two presses.

`Triple'
     Three presses.

   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. If necessary, you can use the %K
notation described below to print out the keysym name for a particular
key.

   Every script bound to an event has these substitutions performed on
it before it executes:

`%K'
     The keysym corresponding to the event, substituted as a textual
     string.

`%%'
     %

`%C'
     When C is a single character other than the above, the behavior is
     undefined.

   If a script terminates with the command `break', then no further
scripts that match the event are evaulated. This can be used to ignore
the builtin bindings which are checked after user defined bindings.

   Examples:

     key set <Key> {echo %K}

   Print out key events as they occur.

     key set <Escape> {write flee}
     key set <Double-Escape> {write quit}
     key set <Triple-Escape> {exit}

   Send "flee" to the mud when `Escape' is hit once.  Hitting `Escape'
twice sends "flee" and then "quit".  Hitting `Escape' thrice sends
"flee" and "quit" to the mud and then exits.

     key set a break

   Prevent the key a from causing `a' to be inserted in the input entry.


File: mmucl.info,  Node: mmucl,  Next: parse,  Prev: key,  Up: Procedures

mmucl
=====

   Query various information about the client.

   Usage: `mmucl option arg...'

   Options:

`lib_dir'
     Return directory where Mmucl was installed.

`rc_dir'
     Return directory where user config files are kept.

`host'
     Return last host connected to or an empty string.

`port'
     Return port of last host connected to or an empty string.

`version'
     Return Mmucl version.

`connect'
     Return a bool indicating connection status.

`interface'
     Return interface being used.

   Examples:

     glob --nocomplain [file join [mmucl rc_dir] chars]

   Get a list of all the character config files.


File: mmucl.info,  Node: parse,  Next: reconnect,  Prev: mmucl,  Up: Procedures

parse
=====

   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.


File: mmucl.info,  Node: reconnect,  Next: sub,  Prev: parse,  Up: Procedures

reconnect
=========

   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 <Key-F12> reconnect

   Try to reconnect every time F12 is pressed.


File: mmucl.info,  Node: sub,  Next: textin,  Prev: reconnect,  Up: Procedures

sub
===

   A sub consists of a format pattern and a subspec.  The sub replaces
every occurence of its pattern in mud output with its subspec. The
command `rxp_sub' is exactly the same except that it uses regular
expressions. *Note Patterns::, for information on pattern matching.

   Usage: `sub option arg...'

   Options:

`set FORMAT [SUBSPEC]'
     If SUBSPEC is given, create a sub.  Otherwise return FORMAT's
     subspec.

`names [GLOB *]'
     Return all the sub names that match GLOB.

`delete -- GLOB'
     Delete all the sub that match GLOB.  The switch `-exact' forces
     literal string matching of GLOB.

`print [GLOB *]'
     Print to the display all the subs that match GLOB.

   While replacing a pattern with a subspec the following substitutions
in SUBSPEC are done:

`\n'
     The nth match of the pattern.

`\0'
     The whole string matched.

`&'
     The whole string matched.

`\\'
     \

`\&'
     &

   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 ^%s$name%s ""
     }
     
     proc ungag {name} {
         sub delete -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'.


File: mmucl.info,  Node: textin,  Next: write,  Prev: sub,  Up: Procedures

textin
======

   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.


File: mmucl.info,  Node: write,  Prev: textin,  Up: Procedures

write
=====

   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"


File: mmucl.info,  Node: Feedback,  Prev: Procedures,  Up: Top

Feedback
********

   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'



Tag Table:
Node: Top241
Node: About694
Node: Copying1028
Node: Overview2586
Node: Tutorial3514
Node: Scripts7467
Node: Syntax8223
Node: Basics15790
Node: Errors18498
Node: Arrays19817
Node: Lists20697
Node: New commands21436
Node: Tips22666
Node: Examples23387
Node: Patterns24129
Node: Format25077
Node: Regexp26569
Node: Glob28741
Node: Procedures29603
Node: action31265
Node: alias32935
Node: bell34749
Node: char34970
Node: check36310
Node: cline38135
Node: color38915
Node: config40101
Node: connect42078
Node: disconnect42856
Node: dump43165
Node: echo44090
Node: exit45279
Node: help45550
Node: key45843
Node: mmucl49112
Node: parse49822
Node: reconnect50939
Node: sub51272
Node: textin53068
Node: write53449
Node: Feedback53760

End Tag Table
