P O W W O W Help and Commands

Documentation last modified Oct 09, 2007

INTRODUCTION

powwow is a client program, which replaces telnet for the lazy mudder who wants some (only some?) extra features. It is primarily designed for DikuMUDs, but nothing prevents its use for other types of muds. powwow is based on another client, cancan, and cancan was originally inspired by tintin (yet another client) by Peter Unold (pjunold@daimi.aau.dk), but is entirely re-written. powwow also implements the MUME remote editing protocol, which enables you to edit texts on the mud using your own favourite editor, several texts at once if you have a windowing terminal.

STARTING POWWOW

Powwow maintains definition files where aliases, actions and mud addresses are saved. Powwow is then called by:

$ powwow definition-file

(the $ above stands for your prompt, do NOT type it)

If the definition file doesn’t exist (as the first time you use powwow) you are asked for a host name and port number. This will then be stored in the file. The file will be updated every time you type ‘#save’ or when powwow terminates. The file is in plain text, so you can edit it if you want. It makes sense to have one file for each mud you play, or for each set of definitions you use in the same mud.

If the environment variable POWWOWDIR exists, that directory is first searched for definition files and new files are created there rather than in the current directory, unless definition-file contains a slash (“/”).

The file ‘Config.demo’ is a demonstrative definition file provided together with powwow to help you building your own configuration. Look at it: there are many useful examples and non-trivial code to fully use powwow.

You may also start powwow with:

$ powwow netaddress portnumber

but nothing will then be saved.

In alternative you can simply type:

$ powwow

and you will enter test-mode: you will be able to use internal commands but you will need to start a session manually (#connect main <address> ) if you want to connect to a MUD.

To solve the problem met in MUME, where you may have to try many different servers to connect to the game, a fourth syntax has been added:

$ powwow definition-file netaddress portnumber

With this syntax powwow reads settings from definition file, but overwrites the old address with the newly specified one.

Note: If you have several sessions (different invokations) with the same definition file active simultaneously, the settings changed in one session can be overwritten by a change in another session.

QUITTING POWWOW

At any time, you can type #quit to exit from powwow. Be careful, as #quit brutally closes the connection to the mud, without renting your character. Normally, you want to log out gracefully from the mud before doing that. If you wish to cut your link manually, you can also press the break key on your system twice (usually Control-C or DEL) (You must hit it twice because hitting only once is used to stop command parsing - see the bottom of this file).

POWWOW TEST MODE

There are various ways to enter powwow test mode:

typing powwow from you command shell(You will have to load your definition file manually if you need it, using the following command: #load ) starting powwow with a definition file that does not contain a ‘#host’ line or contains a ‘#host’ alone, without any address starting powwow opening one or more MUD connections, then closing them all. (You’ll need to have #option quit disabled or powwow will exit when closing the last connection)

Remember that to connect to a MUD from test mode you must use: #connect main <address>

COMMAND CHAINING

Powwow allows you to type several commands on one line separated by the ; character. If you want to use a semicolon literally, prefix it by a backslash (). (Backslashes must of course be escaped too if used literally.)

Examples:

> n;get coins;s rapidly rescue some money
> say No beer? \;) semicolon must be escaped

In addition, you must also surround every list of commands by braces: ‘{’ and ‘}’. The only exception (as you can see from the example above) is when you type multiple commands from keyboard: in that case, and only in that, braces are not needed. Also, if you want to use a { or } literally, prefix it with a backslash as you do with semicolons.

Another use of semicolons is to send a character to the MUD you are connected to. Infact powwow sends a every time it meets a null command (0 chars) followed by a semicolon.

Examples:

> press only: send a
> ; press ; and then : same effect
> ;; send two
> ;;; three ...

Of course multiple `` are considered as multiple commands, so you usually have to surrond them with braces. If directly typed from keyboard, the braces are optional.

> {} do nothing
> {;} send a
> {;;} send two
> {;;;} and so on...

The verbatim mode disables this special meaning of semicolons and braces, and the #quote command lets you switch between verbatim and normal mode.

COMMAND CONTINUATION

Long lines can be continued by ending each intermediate line with a backslash (). This way long and complicated aliases can be written a somewhat readable format. For example:

#al drau={#send ("get tail "+$hcon);#send ("get fur "+$hcon);#send ("get vial "+$hcon);#send ("get tarragon "+$hcon);put tail kit;put fur kit;put vial kit;put tarragon kit}

Could be written (somewhat) more legibly as:

#al drau={\
#send ("get tail "+$hcon);\
#send ("get fur "+$hcon);\
#send ("get vial "+$hcon);\
#send ("get tarragon "+$hcon);\
put tail kit;\
put fur kit;\
put vial kit;\
put tarragon kit\
}

Note that when powwow saves your aliases (e.g. you leave #file defined) that it will not preserve this formatting, so it is most useful if you use a file that is not saved over on exit. For example, if you use a single configuration file that calls several smaller configuration files that are grouped by similar intent, like having an xp counter script, a prompt script, etc.

SPECIAL COMMANDS: ALIASES AND ACTIONS

Alias definition

#alias [name[=[command]]]

Aliases are abbreviations for longer, frequently used commands. As all powwow commands, they are only recognized at the beginning of a line or directly after a semicolon, an open or closed brace. When an alias is used, the first word following the alias name is placed in the variable $1, the second in $2, etc… up to $9. also, the whole string following alias name is placed in $0.

Then, before executing , every $n in is replaced by its contents.

Examples:

#alias summ=cast 'summon' $0 (then "summ thor" is replaced by
"cast 'summon' thor")
#alias cs=cast '$1' $2 ("cs summon thor" is expanded to
"cast 'summon' thor")
#alias summ (lets you edit the definition of summ)
#alias summ= (removes the alias summ)
#alias (display all defined aliases)
#alias ws={wake;stand} (note that you must use braces)

As noted above, aliases are saved automatically if you started powwow with a file name as argument. Aliases can contain other aliases, and an alias can also contain itself (be careful, or powwow will enter a long - but not infinite - loop) Aliases are not expanded in verbatim mode.

Where aliases contain other aliases, one or more '' can be prepended to $n to delay text substition or to use the symbol $n literally.

Example:

#alias ac=#alias $1=cast '$2' \$0
(then "ac sm summon" will give you a new alias
"#alias sm=cast 'summon' $0")

#alias \==score
(this defines = as an alias for 'score', Note that you must
escape the first = to force powwow to consider it literally)

#alias \`=#history $0
(this defines \ as an alias for '#history'. Note that you must
use ` to escape the \ . Just doing \= would escape the = )

Aliases starting with ‘#’ are allowed and do work, but cannot override any special command.

Automatic command execution triggered on output

#action [[|%][+|-]label] [{pattern | (expression)}=[command]]

When ‘pattern’ is found in a line from the remote host, the ‘command’ is automatically executed. If the pattern contains $n, powwow matches one word of the remote line and puts it in the variable $n. If the pattern contains &n, powwow matches a string (possibly more than one word) of the shortest possible length from the remote line and puts it in the variable $n.

As in aliases, $n can be from $1 to $9. NOTE: $0 is a variable as well, but #action automatically places in it the whole line from remote host. As well, &n can be from &1 to &9.

Warning: powwow does NOT print on screen lines from MUD that are intercepted with an #action. So if you want to print them, you must explicitly use a #print or set the #option +autoprint (the help on #print and #option is below in this text) If you want to intercept a prompt, use #prompt instead of #action. (the help on #prompt is near the end of this file)

If the first character of the pattern is ^ (caret), the match will only be possible at the beginning of a line. The match is case-sensitive. If ‘label’ is specified, the action is labeled; otherwise it is numbered.

If an `` is used instead of pattern, powwow evaluates the expression with the inline calculator (see below) and then uses the result as pattern.

Examples:

#action ^You are hungry=eat bread
#action ^You are hungry= (removes the action)
#action ^$1 hugs you={#print;kiss $1}
#action ^$1 says &2=say $1 said $2 (note you must use $, not &
after the =)
#action Jehova={#print;say Who said that? Stone him!}

Labeled actions:

means define, - means define and turn off, while >+ means define and turn on ( > alone is the same as >+ )

#action >fount ^There is a fountain here={#print;drink water}
(named action)
#action -fount (turns off action)
#action +fount (turns it back on)
#action =fount (lets you edit it)
#action -loot is dead! R.I.P.={#print;get all from corpse}
(define and turn off the action)

#action >joke ("^$1 says '&2;)'")= wink $1
(you must either use this syntax or escape the
; to force it to be considered literally)

#action >argh ^$1 tells you 'hello \`=tell $1 I heard you
(as in #alias, \ must be followed by ` when you
need the \ to be followed by a special char
and you do not want this char to be escaped)

If you have compiled powwow with -DUSE_REGEXP and use % instead of > you define an action that uses an Extended POSIX regexp to match instead of the standard matcher.

#action %first ^([[:alpha:]]+) ([[:digit:]]+)=#print $2 counted $3.
(matches abc 123)

Note that if the pattern starts with ‘(’, it is evaluated, which means that a regexp that starts with ‘(’ has either to be surrounded by (“…”) or to be prepended by a backslash. Also note that powwow requires parentheses to be balanced: for example, \(.+|\) would be a valid regexp pattern as the backslash gets removed by the unescaping, but powwow will choke on it as the first parenthesis is escaped while the second is not.

#action %second ("(..+)-\\1")=#print Double $1
(matches xyz-xyz)
#action %third \(..+\)-\\1=#print Double $1
(same as above)

For regexp actions, $0 = the line, $1 = the whole match and $2… contain the submatches.

Actions and aliases can run other powwow commands, including #action and #alias.

Example:

#alias calc=#! echo '$0' | bc -l
#alias hungryon=#action ^You are hungry=eat bread

As with aliases, additional 's can be prepended to $n to delay text substitution in actions.

Example:

#action >reply ^$1 tells you={#print; #alias reply=tell $1 \$0}

ACTION GROUPS

Groups allow related triggers to be enabled and disabled together using a single command, instead of toggling them all on or off individually. To put actions in to a group specify the group name after an ‘@’ when the action is defined. For example:

#action >+auto-ride@non-pk ZBLAM! A &1 doesn't want you={#print;stand;ride}

Would create the action auto-ride in the non-pk group. Then if you wanted to toggle off all non-pk actions, you could do it using:

#group non-pk off

And then later to turn them back on, use:

#group non-pk on

MISSING: #PROMPT

There is another special command quite similar to #action: #prompt [[|%][+|-]label] [{pattern | (expression)}=[command]]

You will need to use it only if you want to mess with the prompt that your MUD sends, which is often not needed. Also, to use it you need to understand exactly how powwow recognizes prompts, so the description is considered an advanced topic and is placed near the end of this file, in the “ADVANCED TOPIC: #PROMPT” section.

MISSING: SUBSTITUTION AND UNESCAPING

Also, only intuitive definitions of substitution, delayed substition and escaping/unescaping have been given so far. If you want the real, rigorous thing, read the “ADVANCED TOPIC: SUBSTITUTIONS AND UNESCAPING” section near the end of this file. That section also explains ‘just in time’ substitution, not yet introduced.

SPECIAL COMMANDS: ALL OTHERS

Toggle verbatim mode

#quote [on | off]

In verbatim mode, no alias expansion takes place and semicolons, escapes, braces and are sent as typed, unless the command line begins with a #, so you can still issue powwow - specific commands. This is useful if you want to paste a text from an editor into a powwow session. Type#quoteto turn on the verbatim mode, and type#quote` again to turn it off.

Show/execute commands in history

#history [number]

#history alone shows you the last commands in history, up to the number of lines in your screen. #history -n shows the last n commands in history, and #history n executes the n-th command of the history.

Recursive #history commands (i.e. an #history calling itself or another #history ) are allowed only up to levels of 128 recursions.

Example:

#history 1 (repeat last command)

Add a text or expression to word completion list (not to history)

#add {text | (expression)}

#add puts the text or result of expression (calculator is used to evaluate the expression) in the word completion list. Useful if used together with #action.

Example:

#action >reply ^$1 tells you={#print;#add $1}
(from now on, you can use TAB to complete that name)

Add a text or expression to static word completion list (not to history)

#addstatic {text|(expression)}

Add the text or result of expression (calculator is used to evaluate the expression) to the static word completion list. Example:

#addstatic Tintin Milou (from now on you can always use Tab to complete
these two names)

Note that the static list is not saved when you run #save, and its words will never be overwritten as new words are added.

It is best used from your #init command, for example:

#init ={#identify;#exe safeflee ^You flee head over heels.=
{#print;#put #print You have already fled away!}

(If you type 'flee' from keyboard, you can keep trying to flee using
cursor-up (which gets the last command in history) and key.
When you finally manage to flee, the message above is put in history,
so that further attempts to flee do not lead you again in danger)

Bind keys to enter commands

#bind [edit | name [sequence][=[command]]]

You can bind most function keys and control keys to enter a command for you when the key is pressed. Also, you can redefine a key already used for an editing function (such as the arrow keys). ‘name’ is the label of the key you want to define; you can just use what is written upon it. When defining a new key binding, you will be asked to press it so powwow can record the control sequence your terminal sends. If you want, you can specify the control sequence directly in the #bind command instead of having to press the key on your keyboard.

Examples:

#bind (lists all user key bindings)
#bind edit (lists all line editing keys)
#bind f1=recite scroll (you'll have to press f1 then)
#bind f1=cast 'sanctuary' (change existing definition)
#bind f1 (lets you edit the definition)
#bind f1= (removes the key)
#bind f1 [[A=cast 'heal' (also tell powwow that f1 on your
keyboard sends ESC [ [ A, so you
do not have to press it)

NOTE: if there is already something on your input line, powwow does not ruin it when you press f1 (or any other #bind), but executes the command you want and then shows you again the input line.

#bind f5=&prev-line (&prev-line is one of the reserved commands for
line-editing functions, see bottom
of this file)
#bind Up=u (Up is an editing key, but can be redefined)

By default, the vt100 numeric keypad is partially used to walk around with:

Key 2: s Key 3: d Key 4: w Key 5: exits Key 6: e Key 7: look Key 8: n Key 9: u

The reserved names that powwow identifies as line-editing functions are at the end of this file, together with the default keys used for them.

Remember that ALL keys can be redefined…

Change the keyboard sequence associated to an existing key binding

#rebind name [sequence]

If you just want to change the control sequence of a binding, but not its name or its effect, you can just tell powwow to ‘rebind’ it. If #rebind is invoked with only the name of a binding, you are asked to press the key you want to rebind. Of course, you will not be asked to press the key if you specify its control codes in the #rebind command.

Examples:

#rebind f1 ^[OP (tell powwow that your f1 key sends ESC O P
and not ESC [ [ A)
#rebind f1 (you are asked to press again f1, useful if you
changed terminal in the meanwhile)

Change the keyboard sequence of all existing key bindings

#rebindall
#rebindALL

#rebindall runs #rebind on most key bindings (skips trivial ones like ^A, ^B, etc.), asking you to press each corresponding key.

#rebindALL does the same, but for really every key binding.

Execute a key as if pressed on keyboard

#key name

If ‘name’ is the label of one of the key defined with #bind, (see above) #key executes the corresponding command.

Example:

If you have already typed

#bind f1=cast 'heal'

At any time, then, you can either:

Press your f1 key on you keyboard Execute the command "#key f1 "

and powwow will execute the command “cast ‘heal’” for you.

Using #key , for example, can be useful from inside an #alias or #action , since powwow cannot press f1 for you.

Since 1.1.5, powwow allows #key also for editing functions. If you have already

#bind Up=&prev-line

and you execute

#key Up

powwow will do what you expect: step to the previous line in history.

Warning: powwow does not distinguish at all between a real key pressed on the keyboard and one faked with #key , so commands executed with #key will also be written in the #record file.

Execute an editing function as if pressed on keyboard

#keyedit function

If ‘function’ is the name of one of the reserved commands for line-editing functions, #keyedit function will run it.

For example, if you already have

#bind Up=&prev-line

the following are all equivalent:

pressing the key Up on your keyboard executing #key Up executing #keyedit &prev-line

Anyway, if you type #key or #keyedit directly from the keyboard the effect is slightly different, as you have to press ENTER to run them and the function &enter-line (which is executed by ENTER) has a few side effects.

Clear aliases, actions or what you specify

#reset {all | name of a list}

Argument: Effect:

all : clear everything (apply all lines below) alias : clear all aliases action : clear all actions bind : clear all key bindings and restart with default settings. Note that also editing keys are resetted to default function. at : clear all delayed commands in : (same thing) mark : clear all markers prompt : clear all prompts var : clear all variables

Mark certain output

#mark [pattern[=[attribute]]]

This command highlights a part of a line in your output in the way you choose (if your terminal supports it). See the section “ATTRIBUTES: COLORS AND OTHER HILIGHTINGS” about the syntax of attributes.

Wildcards are allowed in the pattern, and syntax is very similar to #action : $ matches a single word, & matches any string.

Examples:

#mark Sizzler=bold (mark `Sizzler' in bold)
#mark Sizzler (lets you edit the above definition)
#mark Sizzler= (Sizzler is no longer put in bold)
#mark (lists all markers)
#mark {&}=inverse (mark in reverse any string in { }
note that also the { } are highlited)
#mark ^You=yellow (mark `You' in yellow only if it appears
at the beginning of a line)
#mark \^=on blue (mark a literal ^ )

Load a shared library module

#module [module name]

This loads a shared library module by name, if supported by your system. The name of the module should be included in the documentation that came with the powwow extension, for example to load the perl module you would use:

#module perl

Which gives you the perl command that can be used like:

#perl powwow::exec( "say it is " . scalar(localtime()) )

The commands added and their syntax varies depending on the module.

Set/show priority for new actions/marks

#nice [{number | (expression)} [command]]

When #nice is 0 (default) powwow puts new actions at the bottom of the action list (and same thing for marks). If you want to put new actions/marks in another point of the list, just set #nice to the corresponding value:

If you specify a command after ‘number’, the new #nice value is used only for that command, then the old value is restored.

Examples:

#nice 12 (tells powwow to put new actions/marks in the 12th
(place of the list)

#nice 4 #mark Grizzly=red on blue (put the mark in the 4th place of
the list)

Note that #nice works only for new actions/marks: if an action/mark is already defined, you cannot change its place in the list.

Input highlighting

#hilite [attribute]

This sets the attribute of your entered text to the given attribute. Just #hilite turns it off. See “ATTRIBUTES: COLORS AND OTHER HILIGHTINGS” below for more syntax.

Set standard colours

#color [attrib]

(This command exists only if BUG_TELNET is defined, to cope with deficiencies of NCSA telnet 2.2) Set your standard foreground and background to the colours you specify. #color returns to the default colors for your screen

Capture output to file

#capture [[>]filename]

This captures all output from the main MUD connection and your typed commands to a local disk file. To close the file and end the capturing, type #capture without argument. If the filename starts with a ‘>’, new text will be appended to the end of the file instead of overwriting it. You can only capture output to one file at a time.

Example:

> #capture message
> look at board
> #capture

It is possible to capture in the #capture file even text that you have already received: see #setvar buffer .

Record typed commands to file

#record [filename]

This records all text typed from keyboard to a local disk file. (output from remote host is not recorded) To close the file and end the recording, type #record without argument. You can only record typed text to one file at a time, but #capture and #record can be active at the same time on different files.

Example:

> #record walk-home
> n;e;e;u;n;w;s
> open door
> s
> close door
> sleep
> #record

Capture output to file, with timestamps

#movie [filename]

This is similar to #capture , but adds timestamps to each line received from the main MUD connection or typed from the keyboard, to allow replay at correct speed. The program powwow-movieplay for replay is included with powwow sources. Usage: powwow-movieplay . To convert a movie to plain ASCII, the program powwow-movie2ascii is included too. Usage: powwow-movie2ascii .

It is possible to capture in the #movie file even text that you have already received: see #setvar buffer .

Execute a shell command

#! command

Executes a command using /bin/sh. Powwow waits until your shell finishes, but you can put jobs in the background with & as usual.

Example:

> #! who | sort | less
> #! nethack
> #! xbiff &

Note that semicolons, escapes and braces need to be escaped if they are to be sent to the shell. If your shell has job control, you can also suspend powwow with ^Z as usual.

Put a string in the edit buffer automatically

#prefix [string]

Each new line you type will automatically begin with the prefix string. You can of course edit or delete the inserted string as usual. To remove the prefix, just issue a #prefix command without arguments. This is handy when you are talking to someone, for example.

> #prefix tell arthur

Help

#help [keys | math | command]

Shows a list of powwow’s commands. #help keys shows the editing keys. #help math show help on inline calculator. You can also have help on specific commands, using for example #help alias or in general #help . A help file is needed and provided for this last feature of #help , and powwow will look for the file “powwow_help” in the directory specified by the environment variable POWWOWHELP. If this variable does not exist, powwow looks in current directory.

Command repetition

#n command

This repeats the command n times. Example:

> #5 buy bread (buy five breads)

Alternatively, you can use this syntax to repeat a command n times:

#do (expr) command

In this case, powwow evaluates the expression, and uses the result as counter.

Example:

> #do (3*8) north (go north 24 times)

Iterate a command (#while)

#while (expression) command

This syntax repeats a command while expression (evaluated with calculator) keeps true. (see below for help about calculator) As with #alias and #action , the $n and @n in command are replaced by their values. (Even if you can, using @n after the = in #action and #alias is useless, because you have no way to assign them a non-zero value. This is the reason why we did not talk about them in the #alias and #action section)

Example:

#while (@0
evaluate 'check', if result is 0 (false) stop repetition
execute 'command'
evaluate 'loop' (if specified)
restart from 1)

As with `#while` , `#for` performs the parameter substitution in 'command', so the only significative difference between `#while` and `#for` is that `#for` allows you to execute an initialization before the repeat cycle.

Example:

#for (@1=32; @1mume *** MUME=#identify #identify foo bar (where foo and bar are aliases that do something useful)


### Identify as a IAC GA compliant client

#request prompt


This command sends an identification string to the server, to indicate that the client supports (and wants) the special sequence IAC GA at the end of each prompt. This helps the client to automatically detect the prompt, and can be used as alternative to `#prompt / #isprompt` if all you want with the prompt is detecting it (and not altering it)

BIG WARNING: this is experimental and not tested!

Example:

#action >mume *** MUME={#print;#identify;#request prompt} #request prompt


### List all editing sessions

#edit


This command shows your active editing sessions, with a brief description and their number.

### Cancel an editing session

#cancel [number]


Without an argument, all editing sessions are cancelled; otherwise, only the given session is cancelled. The corresponding editor processes are brutally killed.

### List/turn various options on/off

#option [[+|-|=]option-name]


Currently available option names are:
`exit, history, wrap, compact, debug, echo, info, keyecho, speedwalk, wrap, autoprint, buffer, reprint, sendsize, autoclear, words`

`#option +name` : turns an option on
`#option -name` : turns it off
`#option name` : toggles it
`#option =name` : reports its status

<h4>#option exit</h4>
If the `exit' option is on, powwow automatically quits when the last connection is closed. Otherwise, to quit powwow you need to manually type `#quit'

<h4>#option history</h4>
With `history' option on, powwow writes into your savefile also all your commands in history

<h4>#option words</h4>
With `words' option on, powwow writes into your savefile also your word completion list

<h4>#option compact</h4>
Normally, powwow does not touch the prompts on screen while you play. In `compact' mode, instead, lines containing only a prompt are deleted when further messages arrive from the remote host.

WARNING: this command works correctly only if you have #prompts which correctly run #isprompt. Otherwise it may occasionally erase some lines from the screen.

<h4>#option debug</h4>
Normally, powwow does not print on screen the command lines it executes. When `debug' is on, every line executed by powwow is also echoed on screen, so that you can check if your code works correctly (warning: this prints LOTS of lines on your screen)

<h4>#option echo</h4>
Normally, powwow echoes on your screen each command sent to remote host but not directly typed (example: aliases and actions sending text to the MUD). When `echo' is off, such commands are still sent to host, but not echoed on screen.

<h4>#option info</h4>
Normally, powwow prints on screen some messages each time you define/edit/delete an #alias, #action, #bind and similar. When `info' is off, those messages are not typed at all. (But errors are still printed on screen)

<h4>#option keyecho</h4>
Normally, powwow echoes on your screen the commands sent to remote host when you hit a key associated to a #bind. When `keyecho' is off, such commands are still sent to host, but not echoed on screen.

<h4>#option speedwalk</h4>
With `speedwalk' on, a command consisting of only lowercase n, e, s, w, u, d and numeric digits is considered to be a walk sequence. The numeric digits specify the number of times to repeat the direction immediately following.

Example:

esssu (walk east, 3 south, up) e3su (same as above)


<h4>#option wrap</h4>
Normally, powwow wraps words that would have been cut by the right margin to the next line. This command lets you turn it off and on.

<h4>#option autoprint</h4>
If `autoprint' is on, powwow prints lines matched by an #action even without an explicit #print.

<h4>#option sendsize</h4>
Usually powwow does not send the window size to the MUD unless asked. If you want to send the window size automatically upon connecting, you may enable this option.

<h4>#option autoclear</h4>
Powwow normally erases the input line before executing commands from spawned programs, but that is slow and causes flicker. If autoclear is disabled flicker reduces to minimum, on the other hand spawned programs must then execute #clear before sending anything to screen.

<h4>#option reprint</h4>
If `reprint' is on (off by default), powwow prints again commands sent to the mud but not yet executed.

WARNING: it works only if you use #prompts which correctly run #isprompt.

++++ example: ++++

*>look south down

The High Path

*>Path Climbing a Hill

*> Alas, you cannot go that way.

*> ++++ becomes: ++++ *>look south down

The High Path

*>(south) Path Climbing a Hill

*>(down) Alas, you cannot go that way.

*>


### Show current version

#ver


Displays the current version, some compile options and (if your compiler supports it) when powwow was compiled.

### Multiple connections handling commands

#connect [session-id [initstr] [host port]] connect a new session / list sessions #snoop session-id toggle output display for session #zap session-id disconnect a session

set as default session

command execute command on session


No docs here. If multiplaying is allowed on you MUD (and many do NOT allow) you can experiment a little to find how they work. Or you can open two connections to two different MUDs :)

### Spawn an external program

#spawn session-id command


Creates a new session, connected to a shell command instead of a MUD. Writing to `##` sends data to the command's standard input, while the command's standard output is executed as if typed from keyboard. Useful if you are a programmer and you want to create very complex filters or robots, for which `#actions` are too limited. Command's standard output *MUST* terminate with a newline ('\n') in order for powwow to execute it. You can send multiple commands at once terminating each of them by either a semi-colon ';' or a newline '\n', except for the last one which (I repeat) *MUST* terminate with a newline.

You can close these sessions with `#zap` and list them with `#connect` as usual.

Depending on how lazy you are, you can choose two different ways to have spawned programs print to screen:

The first is automatic, but slow: with `#option +autoclear` powwow clears the input line before executing every line received from the program. This is of course slow and causes flickering.

The second is more complex, but faster and reduces flickering to the minimum: set `#option -autoclear` from the beginning, then have the program execute `#clear` before printing.

### Exit from powwow

#quit


Very little to say here. Just remember that `#quit` brutally closes all mud connections that are still open, without renting your characters. Quite likely, you want to rent them all before quitting.

### Set definition-file and save settings to it.

#save [definition-file]


Useful after you write large chunks of code. Remember anyway that powwow automatically saves the settings before exiting.

`#save` actually writes settings to a temporary file and overwrites the definition file only if write succeeds. This is to avoid wiping out definition file in case of `disk full' or other errors.

### Set definition-file and load settings from it.

#load [definition-file]


Useful if you want to undo the changes in your settings.

NOTE: current settings are completely erased before actually loading from file. In case of errors, powwow reloads the default editing keys.

If you just want to add the contents of a file to your current settings use `#exe
`#net` : show amount of data transmitted to and received from the remote host.
`#cpu` : show the CPU time used by powwow. (if powwow does not find the symbol CLOCKS_PER_SEC defined at compile time, the result may not be in seconds...)
`#time` : show current time/date. Useful if you want to use `#at` .
`#beep` : ring your terminal's bell (like `#print (*7)` )

### List/delete/define/edit delayed commands

#at [label [(time-expression) [command]]] or #in [label [(delay in millisec.) [command]]]


If you want to tell powwow to execute the command 'kill wolf' 2 seconds after you type it, use this command:

#in attack (2000) kill wolf


Let's explain the command:

'attack' is a label, exactly as in `#actions` , and is used only to have a quick reference to the delayed command; (2000) means wait 2000 millisec., i.e. 2 seconds; 'kill wolf' simply executes kill wolf, as if typed from keyboard.

Of course, you can use an expression (as complex as you like) instead of the number in parentheses, and the command can also be an alias, internal command or even another `#at` or `#in` . (of course you can use multiple commands by placing them in `{}` )

If you do not specify the command, powwow assumes the label is already defined, and changes its delay. A delay less than zero means the delayed label is disabled, but still in powwow's memory, similar to what happems when you turn off an `#action` . A delay of zero deletes the delayed label.

If you specify only a label, powwow lists it. If you specify nothing, all delayed labels are listed.

The `#at` command is nearly equal to `#in` , but assumes the expression in ( ) is a time. For example (114520) means 11:45:20 , and ("114520") is the same. After evaluating the time, powwow converts it into a delay, and places the delayed label in the same list of `#in` . NOTE: it is not possible to delete a delayed label using `#at` , since (0) means midnight. One more thing: it is not possible do define disabled labels using `#at` , because a time disint ^&1 disintegrates &2=#print $1 DISINTEGRATES $2
put the text in upper case
#action >disint ^&1 disintegrates &2=#print ($(1)+" DISINTEGRATES "+$(2))
same thing, but using calculator

#print ` to `` of its output.

Also here, you can use expressions instead of Bourne shell command, start and end, and powwow still begins from first line if `` is not specified and/or stops at the end of the output if `` is not specified.

Both these special features are supported ALSO in `#send` , `#exe` , `#emulate` and `#var` .

### Send text or result of an expression to MUD

#send [ | !](expression ; file)


Evaluate expression and get result, then write result into file. By default, text is appended at the end of the file.

If > is specified, `#write` deletes the contents of the file before actually writing the text.

If ! is specified, `#write` assumes second parameter to be a Bourne shell command (instead of a file name) that is executed using the text as its input.

Example:

#write ($test; “myfile”) (append contents of $test to myfile)

#write !(“55+12”;“bc -l”) (execute ‘bc -l’ writing text to its standard input)


Advanced `#write` usage:

If you are using a terminal allowing multiple windows (an X11 graphic terminal for example) it is possible to duplicate/split powwow output to multiple windows using `#write` . This is more a UNIX topic rather than a powwow-specific one, but that's it. Here is a brief summary:

First, compile the `catrw` mini-program i.e. type

$ make_it catrw


if the above worked, type

$ mkfifo fifo


This will create a special file named `fifo' in the directory (any other name would do, of course) Then you have to open another window. This depends on the terminal you're using, but for X11 terminals the following works:

$ xterm &


On the second window, type

$ exec catrw fifo


(in case this gives you an error, try just `catrw fifo') Now return to the first window and start powwow normally. To send text to the second window from within powwow, type:

#write (“some text”; “fifo”)


You should see `some text' (without the quotes) immediately appear in the second window.

Of course you may now want to send text automatically to the second window: just use `#write ( ; "fifo")` from within an `#alias` , `#action` or whatever you like.

P.S.: for experienced users: if you are using the `bash' shell, you don't need `catrw' as you can use

$ exec cat <> fifo


instead of the above

$ exec catrw fifo


### Set/show internal variables

#setvar name[={number|(expr)}]


Evaluate the expression and get result, then set the internal variable `name' to that value.

Known internal variables are:

buffer: with `buffer' different from zero, powwow saves the most recent text from the MUD in a circular list (which is `buffer' bytes long) and writes it at the beginning of #capture and #movie files when you open them. This is useful if something important happens suddenly and you want to log it somewhere: you can start #capture and/or #movie even _after_ the event has happened and it will still get written to the file. if `buffer' is zero (default), powwow starts logging text from the MUD only at the moment you activate #capture or #movie. To discard the text stored in memory by `buffer', change its value (for example, set it to zero and then back to a non-zero value).

lines: the number of lines your terminal has. Powwow usually autodetects it correctly, but on few terminals you may have to set it manually.

mem: the maximum length of a text or string, in bytes. The default is 0 (zero) which means no limit. I added it only to prevent bringing down the whole system with things like `#while (1) #($foo += $foo + "x")` Consider it an emergency setting, as powwow _discards_ text and strings longer than the limit. The failsafe limit set when loading a savefile from an older version is 1Megabyte, which won't give any problem (like increased memory usage) as powwow allocates memory only when it *has* to.

timer: the number of milliseconds since program start. It can be changed to synchronize with an external clock like MUD ticks.

Example:

#setvar timer=0 (reset internal timer to 0) #setvar timer=20000 (make internal timer restart from 20000 milliseconds) #setvar timer (show timer and let you edit it)

#setvar mem=1048576 (max strings length is now 1Megabyte)


### Send raw data to MUD

#rawsend {text | (expression)}


This is mostly a MUD debugging tool, but it can be useful in some cases. Like its cousin `#send` , `#rawsend` evaluates the expression (or unescapes the text) and sends the result to the MUD. The difference is that `#rawsend` does NOT add a final newline, nor does IAC escaping to protect ASCII 255 characters. On the other hand, `#rawsend` can handle ASCII 0 characters, while plain `#send` can't.

### Send raw data to screen

#rawprint {text | (expression)}


Like its cousin `#print` , `#rawprint` evaluates the expression (or unescapes the text) and sends the result to the screen. The difference is that `#rawprint` does NOT add a final newline. On the other hand, `#rawprint` can handle ASCII 0 characters, while plain `#print` can't.

## INLINE CALCULATOR

The inline calculator is used to evaluate expressions inside `#()` , `#print ()` , `#exe ()` , `#send ()` , `#if ()` , `#while()` , `#for ()` , `#do ()` , expressions in pattern of `#actions` and in other commands allowing ()

The inline calculator recognizes the following objects:

<h4>numbers (only integers are supported)</h4>

decimal numbers: simply write them.
hexadecimal numbers: use '#' as prefix: #F is 15, #a0 is 160, and so on.
numbers in any other base: use base# as prefix: 2#101 means 101 in base 2 (that gives 5) 7#14 gives 11, etc...
if you use negative non-decimal numbers, you must put '-' before the base: - 2#101 is -5, 2#-101 causes an error.
it is possible to chain more than one '#': 3#12#100 = (3#12)#100 = 5#100 = 25
both base and argument must be numbers, not variables: things like 7#@count or @count#7 are not allowed, you will have to use an #exe for that.

<h4>quoted-strings (i.e.: strings in " ").</h4>
NOTE: since version 0.6d, powwow performs unescaping on quoted strings when they are evaluated. For example `"\""` is the string that contains the character " only.

<h4>timer (number of milliseconds since last timer reset)</h4>

<h4>map (string containing the last 999 steps you walked, as the #map command)</h4>

<h4>variables:</h4>

`@n` with n within -50 and 9, are numeric-variables
`$n` with n within -50 and 9, are string-variables
Since version 0.8, also named variables are supported: `@any_name1` , `$any_name2`
The name following @ or $ can contain any of these chars: uppercase or lowercase letters ('A'...'Z' and 'a'...'z'), underscore ('_'), numbers ('0'...'9'). Anyway, the first char of the name must NOT be a number.
Remember that powwow is case sensitive: `$test` and `$Test` are NOT the same variable
Named variables are created the first time you use them and can be deleted only using the `#var` command
A special named variable is `$prompt` , which contains the current prompt. It cannot be deleted. Another special variable is `$last_line` , which contains the last non-empty line received from the MUD. Again, it cannot be deleted.

<h4>Difference between the various kind of variables:</h4>

Numbered variables with negative counter (`@-50..@-1` and `$-50..$-1` ) and named variables are global: They can be accessed at any time, but cannot be used for the substitution performed by `#alias` , `#action` , `#while` and `#for` .
Instead, numbered variables with positive counter (`@0..@9` and `$0..$9` ) are local: A new set is created (and initialized to zero) every time powwow executes an `#alias` , `#action` , `#while` or `#for` , and the old set is made invisible. After the `#alias` (or `#action` , `#while` , `#for` ) is executed, the old set is restored. Note that also `@0..@9` can be used for parameter substitution, and not only `$0..$9` .

<h4>Variable names as expressions:</h4>
The symbols $ and @ are implemented as normal operators, which means that variable names can be arbitrary expressions. For example,

$(1-3) is the numbered variable $-2 @(“foo”+“bar”) is the named variable @foobar $1 is the variable whose name is in $1


<h4>operators between numbers:</h4>
`++ -- + - * / % + - > >= == != & | ^ && || ^^ = *= /= %= += -= >= &= ^= |= &&= ^^= ||= , ( )`

(% and %= always return non-negative values)

(no help on these operators, see a C-language manual)

(note: unlike C, operators &&, ^^ and || always eval both arguments)

<h4>random number generator:</h4>

rand positive-number (return a random number between 0 and n-1)


<h4>operators between strings:</h4>

`+` chain two strings
`=` assign a string to a string-variable
`+=` append a string to a string-variable
`-` compare two strings: result -1 if s1s2, 0 if s1==s2
` >= == !=` compare two strings
`.?` number of chars in a string
`:?` number of words in a string
`?` position of first occurrence of second string in the first
`*` convert first char of a string into its ASCII code or vice versa
`%` convert string into its numeric value or vice versa

<h4>operators between a string and a number:</h4>
(string is first argument)

`: n-th` word of a string
`. n-th` char of a string
`: : . .` return part of a string, in this way:

`:` before > or
`.` before > or
`:` after > or
`.` after > or
`>` means: return from marked word/char to end
`

so we get:

`:
`:> n` : from the n-th word (include) to the end
`
`>: n` : last n words

and similarly for `. .`

`*` : repeat a string n times: "ab" * 3 gives "ababab"
`*=` : usual shortcut: `$x *= n' is the same as `$x = $x * n'

<h4>functions for low-level color handling:</h4>

`noattr` : (string containing the escape sequence to reset terminal colors and attributes -- bold, underline, inverse)
`attr "quoted-string"` : (return the escape sequence needed to turn on the attributes and colors in the string. Syntax of the string is the same as `#mark` , `#hilite` , etc)

Examples:

#print ($5=“Hello, world”) (assign “Hello, world” to $5 and print it)

#print (“This is a test”>:3) (print from the 3rd word from the right till the end of the string) Result: “is a test” is printed on screen

#action >+exp ^You have scored $1 exp={#print;#print (“You gained " + ( $1 - @-5) + " exp. points since last score”); #(@-5 = $1)}

(when you type ‘info’ in MUME, one of the lines you get is: You have scored xxx exp. points … The #action above intercepts this line, prints it, prints the difference between your current score and the contents of variable @-5, then copies your current score in @-5)

#print ($5 = (attr “bold green”) + “Hello, world!” + noattr)

(same as first example, but with colors/attributes. Rememeber to print noattr at the end of every colored line, or everything appearing on the screen after your line will be colored as well)


## HOW INLINE CALCULATOR IS IMPLEMENTED

Info and hints to get the most out of calculator and/or hack it. The structure `op_list[]` defined in xeval.c contains definitions for all the implemented operators, one for each line. Have a look at it to find things like:

precedence (first number in each line)
associativity (LEFT or RIGHT)

LEFT means that 1+2+3 actually is (1+2)+3
RIGHT means that 1+2+3 actually is 1+(2+3)
(replace numbers and operators with what you are actually using)

if it is unary, i.e. needs ONE argument

PRE_UNARY means that the operator comes before its argument,
POST_UNARY is the opposite

or binary i.e. needs TWO arguments

Note that stuff like `attr', `rand', `@' and `
are actually implemented as PRE_UNARY operators (named variables are treated as an exception to this), thus `$(1+5)' and `attr ("bold"+" "+"inverse")' are fully allowed. Also note that using `$(5)' is a good way to avoid the parameter substitution performed by aliases, #action, #for, #while and use instead the actual variables. `timer', `map', `noattr' are implemented as read-only values: the calculator simply substitutes them with their value Remember that there is a , (comma) operator: Instead of `#(foo);#(bar)` you can use `#(foo, bar)` Using comma operator is easier for both you and powwow, since it uses a single command instead of two. ## ATTRIBUTES: COLORS AND OTHER HILIGHTINGS Some commands use attributes to specify the visual appearance of text. The following attributes are available: `bold, blink, underline, inverse` -- the obvious effects `reverse` -- same as inverse `[color] [on color]` -- foreground and/or background Colors are: `black, red, green, yellow, blue, magenta, cyan, white` and `BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, none` ('none' means to use default and is implemented as a color) Examples: The following are all valid attributes:

none – no attribute, use default green – only foreground on white – only background yellow on cyan – foreground and background inverse bold – blink red on blue – you can use multiple attributes, but you must put ‘bold’ ‘inverse’ and/or ‘underline’ BEFORE colors


Observe that bold, blink, underline and reverse work with all terminals that support these attributes, but colors only on terminals that support ANSI color escape sequences.

Capitalized colors (BLACK..WHITE) are non-ANSI high intensity colors, and will not work on all terminals (They work on the 'aixterm' terminal emulator under AIX, but they may work on other terminals as well. Let me know if you find other terminals that support them).

Notes for IBM PC and compatibles with VGA or SVGA cards in text mode:

yellow is actually brown
bold is usually represented as high intensity
blink can be represented either with actual blink or high intensity background - depends from card configuration (it is possible to reprogram it - I can send details if asked)

## HISTORY

Powwow keeps in memory the last 127 lines you typed from keyboard. If you want to recall one of them (to correct a mistake for example) you just need to press your arrow-up key or control-p to scroll through the whole history, one step at time (see COMMAND LINE EDITING below in the text for details about editing keys).

Another way to find a certain line in the history is to type the first few chars of it, and then press M-TAB to tell powwow to complete the line for you. If you hit M-TAB repeatedly, powwow will cycle through all the possible completions.

Also, you can use the `#put` command to add a line to history as if you typed it (see above for help on `#put` ).

## WORD COMPLETION LIST

Powwow also remembers the last 512 words you typed from keyboard. This list of words is named `word completion list'. If you have already typed a long or difficult word, you can type the first few chars of it and then press TAB key to ask powwow to complete it for you. Again, if you hit TAB repeatedly powwow will cycle through all the possible completions.

Powwow can also complete the name of any built-in command even if not present in the word completion list.

Also, you can use the `#add` command to add a word to word completion list (see above for help on `#add` ).

## COMMAND LINE EDITING

The default key bindings for line editing follow quite closely Emacs: These are all the keys, together with the reserved names that identify their function (they can be listed typing `#bind edit` ):

Key
Function name:
Description:

^A&amp;begin-of-linebeginning of line
^E&amp;end-of-lineend of line
^B&amp;prev-charbackward one character
^F&amp;next-charforward one character
^P&amp;prev-lineuse previous line in history (step backward)
^N&amp;next-lineuse next line in history (step forward)
^D&amp;del-char-rightdelete character under cursor
BS&amp;del-char-leftdelete character left of cursor
^K&amp;kill-to-eolkill to end of line
^T&amp;transposetranspose previous character with next (if at the end of the line, the two last)
^L&amp;redraw-lineredraw your command line. This is useful if something garbles your input line.
^Q&amp;clear-lineclear input line.
^W&amp;to-historyput current line in history and clear input line. This is useful when you are typing a long line and need to send another urgent command first.
^Z&amp;suspendsuspend powwow in the background
Tab&amp;complete-wordcomplete the word being typed to the last matching word in the history (or added with an #add command; see above). Hit multiple times to browse the possible completions. This is similar to the GNU Emacs M-/ command.
M-Tab&amp;complete-linecomplete the line being typed to the last matching line in the history. Hit multiple times to browse the possible completions.
M-f&amp;next-wordforward one word
M-k&amp;redraw-line-nopromptredraw command line, discarding prompt
M-b&amp;prev-wordbackward one word
M-d&amp;del-word-rightdelete word right of cursor
M-BS&amp;del-word-leftdelete word left of cursor
M-l&amp;downcase-wordturn word to lowercase
M-t&amp;transpose-wordstranspose previous word with next
M-u&amp;upcase-wordturn word to uppercase
Ret&amp;enter-linethe most obvious: execute the typed line
LF&amp;enter-linesame thing, but for ^J key (some terminals send this when you hit return)
(none)&amp;insert-stringinsert on command line the specified chars

M-x means pressing the META or Alt key at the same time as x, or pressing and releasing the escape key, then typing x. The former way doesn't work on all terminals.

^x means pressing the Control key at the same time as x.

If your terminal has arrow keys, they can be used to move the cursor and step around in history. In addition, you can define your own key bindings for sending quick commands (see the `#bind` command). If you have a vt100-compatible terminal, the numeric keypad is predefined for movement (keys 2, 3, 4, 5, 6, 7, 8 and 9).

Remember that ALL keys can be redefined...

A brief note about `&insert-string` :

By default no key is bound to this function, and it works somewhat differently than other editing functions.

For example, say you don't have `{' and `}' on you keyboard (it happens on all italian keyboards -- like mine -- and other ones). Obviously, typing { or } gets quite difficult. A solution is:

#bind F11=&insert-string \173 #bind F12=&insert-string \175


where \173 and \175 are typed normally: a backslash and three digits. Once you defined these two bindings, hitting F11 will be exactly like typing { and hitting F12 will be exactly like typing } .

Another possible use is to enter strange characters or strings:

#bind F10=&insert-string Ro\353ntgen


does exactly what you expect: insert "Roėntgen" on the input line ( ė is the ASCII char (octal)353 or (decimal)234 ) as if you typed it (of course you could also type the first few chars of the name then hit TAB if that name is already in the word completion list...).

## SECURITY

When you define an `#action` that automatically sends something back to the MUD you are connected to, you must be VERY careful since you may allow other players to force you to execute commands. Let's explain better: Suppose you define the following `#action` :

#action >+autogroup ^&1 starts following you.={#print;group $1}


Even though this may look harmless, such an action is potentially lethal, for the following reason: If you receive a text from the MUD containing something like

Cauldron ;remove all;drop all;kill dragon starts following you.


(for example it may be an emote, many MUDs allow it)

powwow will realize that the line matches with the action you defined (remember that &n can match text of every length, even if containing spaces or ; ) and will execute this:

{#print;group Cauldron ;remove all;drop all;kill dragon}


The consequences of such a command can be easily imagined... There are two strategies to avoid such embarassing situations:

1) Use `#send` and calculator. In fact this is NOT dangerous:

#action >+autogroup ^&1 starts following you.= {#print;#send ("group "+$(1))}


(in the worst case you will send some semicolon-separated commands to the MUD, but I saw no MUDs accepting multiple commands as clients do...):

2) Try to use `$n` instead of `&n` , so that semicolons and spaces are skipped.

#action >+autogroup ^$1 starts following you.= {#print;group $1}


WARNING: versions older than 0.7a were bugged and they did NOT skip semicolons (but they skipped spaces), so also using `$n` was dangerous!

If you really need to use a `&n` , check you are not losing security, and if you cannot write safe code, use calculator as in point 1). Note that this is NOT dangerous too:

#action >+autogroup ^&1 starts following you.=group $1


since if someone tries to force you as explained above it will not work, because `#action` allows only ONE command to follow the pattern and you did not place braces around "group $1", so only the first command (in this case "group ") will be executed.

In every case, remember the best strategy is: check what you are doing, and do not lose control. If you are not sure a command is safe, better not to use it.

## LIMITS

Powwow has the following limitations:

Numeric variables are defined as 'long', that means 32-bit integers on most systems.
String variables, text lines and commands by default have no length limits. If you want, you _can_ set a max limit with `#setvar mem` . Powwow discards text and strings longer than such a limit.
Exceptions: the labels/patterns of `#aliases` , `#actions` , `#prompts` , `#marks` , `#in/#at` etc. cannot be longer than 4095 chars. The same limit (4095 chars) applies for the input line. (the number can be changed by modifying the symbol BUFSIZE)
Unnamed ('numbered') variables must have indexes from -50 to 9. (the 50 can be changed modifying the symbol NUMVAR, the 9 cannot be increased due to hardcoded limits)
Inline calculator can hold up to 100 suspended operations, due to parentheses and/or inverted priority of operators. (the number can be changed by modifying the symbol MAX_STACK)
The depth of nested/recursive aliases, actions, prompts, `#while` and `#for` commands is limited to 100 nested calls. (the number can be changed by modifying the symbol MAX_STACK)
The number of loops of a `#while` or `#for` is limited to 10000. (the number can be changed by modifying the symbol MAX_LOOP)
Automap can be at most 999 steps. (the number can be changed by modifying the symbol MAX_MAPLEN)
History can contain at most 127 lines. (the number can be changed by modifying the symbol MAX_HIST) `#history` commands can execute other `#history` commands, up to MAX_HIST levels of recursion.
Word completion list can contain at most 512 words. (the number can be changed by modifying the symbol MAX_WORDS)
Up to 32 MUD (or spawned) connections can be open simultaneously. (the number can be changed by modifying the symbol MAX_FDSCAN)
For all other resources, the only limit is the available memory.

## THE BREAK KEY

It is usually Control-C or DEL (it depends from the terminal you use).

Powwow cannot redefine it, but you need to hit it twice in a row to actually stop powwow. This is because hitting it only once is used to stop command parsing: if you enter a long loop using internal commands (for example: `#while (1) drop 1 coin` ) you can simply press your break key and powwow will immediatly exit from the loop with this message: `#interrupted. Press again to quit.`

If you press the break key again, you will exit powwow. Otherwise, if you first type something, then you press break key once more, you will get again: `#interrupted. Press again to quit.`

## ADVANCED TOPIC: SUBSTITUTIONS AND UNESCAPING

WARNING: this is a bit complicated and not recommended for beginners, as the explanation given at the beginning about $n and \'s might suffice in many cases. So you might skip this paragraph if you want.

Still reading? Ok, this is it:

We described in the beginning that adding \'s to $n delays text substitution in aliases and actions. Actually, every time powwow is asked to execute a command, it can make one or more of the following operations on the command itself before executing it:

<h4>Step (a) : `PARAMETER SUBSTITUTION' or simply `substitution'</h4>

(a1) place in $1..$9 the correct words
(a2) replace every occurrence of $1..$9 with the contents of the corresponding variable. Also replace every occurrence of @1..@9 with the contents of the corresponding variable. Note that if one or more \ are preceding a $n or @n, it will be NOT substituted.

<h4>Step (b) : `JUST IN TIME SUBSTITUTION' or `jit' in short</h4>

(b1) replace every occurence of #{expression} with the value of the expression. Also replace every occurrence of ${name} and @{name} with the contents of the corresponding variable. Again, if one or more \ are preceding a #{expr}, ${name} or @{name}, it will NOT be substituted. This substitution works also for numbered variables ${number} and @{number}.

<h4>Step (c) : `UNESCAPING'</h4>

(c1) Remove ONE \ from every list of consecutive escapes, unless they are followed by one or more ` (i.e. reverse-escaped) For example, \\\$1 is replaced with \\$1
(c2) Remove ONE ` from every list of consecutive escapes immediately followed by a list of consecutive ` For example, @``` is not modified, while \\` is replaced with \\ and \\``` is replaced with \\``

The steps actually executed vary from command to command, but are always ran in order: if both present, (a) always precedes (b) if both present, (a) always precedes (c) if both present, (b) always precedes (c).

When each step is performed/not performed:

Step (a) (substitution) is performed when executing one of the following: aliases, actions, prompts, #for or #while
Step (b) (jit) is performed when executing _any_ command that allows a single instruction, and is executed on that instruction before running it. The list is: #alias, #action, #prompt, #at, #bind, #connect, #do, #for, #identify, #if-#else, #in, #init, #nice, #while. Also performed on normal (not yet implemented for regexp) patterns of #actions before matching them. On regexp patterns, step (c) is made instead.
Step (c) (unescaping) is performed any time that step (a) and/or step (b) are performed. In addition, unescaping is also performed on text (not on expressions) following all #commands that allow plain text: #add, #emulate, #exe, #mark, #print, #put, #send, #var on labels of all #commands that allow labels: #alias, #action, #prompt, #at, #in and last, on text that is not a #command nor an alias before sending it to the MUD, unless the last operation on the text was _already_ an unescaping.

Examples:

#alias fb=cast ‘fireball’ ${target} #var $target=troll fb (effect: cast ‘fireball’ troll) #var $target=dragon fb (effect: cast ‘fireball’ dragon)

#action >chase ^${target} leaves $1={#print; #alias f=$1} (whenever `dragon’ leaves the room, the alias ‘f’ is set to follow it)

#action >chase2 ^${target} leaves $1={#print; #alias f=$1} (the text `${target}’ will be matched literally)


WARNINGS:

Step (b) is NOT automatically performed on text typed from the keyboard so for example `#print ${target}` just prints literally `${target}` and not the contents of the variable. If you need step (b) on text you type, you can do something like: `#alias /=$0` and then prepend all commands with `/ ' : `/ #print ${target}`
Step (b) is not yet implemented for regexp actions/prompt due to internal difficulties. As a workaround, step (c) (unescaping) is instead performed on regexp patterns.
Since powwow 1.1.3, unescaping is performed also on the text coming from substition and jit. This causes subtle incompatibilities with previous versions in case $n contains any \ or \` . I tried to avoid this incompatibility, but it is really complicated to do since I want the text coming from substitution to be subject to jit as well. So you (and me) will have to live with it :-(

## ADVANCED TOPIC: SPECIAL COMMAND #PROMPT

<h4>Automatic command execution triggered on prompts</h4>

#prompt [[|%][+|-]label] [{pattern | (expression)}=[command]]


WARNING: this is quite a complicated topic too. You will only need to read this paragraph if you want to mess with prompts in strange ways, as powwow usually handles prompts correctly.

Second warning: `#prompt` works only on the main MUD connection.

O.K, since you are still reading, let's get a bit technical about powwow internals:

(WARNING: this changed since powwow 1.1.7:)

Unless you use `#actions` , powwow sends immediately to the screen whatever text it receives from the MUD. It sends to screen both newline-ended lines (we'll name these `full lines') and lines not ended with a newline (`incomplete lines'). Now, there are two problems:

there's no way to know whether an incomplete line is actually finished or there is a continuation we still have to receive.
powwow cannot know if the line, or an initial part of it, is a prompt.

When powwow receives a line (either full or incomplete), its beginning part may be a prompt, so it matches `#prompts` on the line. If the beginning part is _actually_ a prompt, `#prompt` should execute `#isprompt` on it, to let powwow recognize the prompt as such.

To be exact `#isprompt` must also specify how long the initial prompt is, so that powwow can split it from the rest of the line. For this reason, `#isprompt` is invoked with a numerical argument: `#isprompt ` or `#isprompt (expression)`

a)If the number (or the result of the expression) is positive and equals to (n), `#isprompt` declares that the initial prompt is (n) characters long.
b)If the number is negative and equals to (-n), `#isprompt` declares that the initial prompt is the same length as the parameter `$n` .
c)If the number is 0 (or is missing), `#isprompt` declares the whole line as a prompt.

Also, if a `#prompt` does not run `#isprompt` , it is interpreted as 'this text is not a prompt'

Putting `#isprompt` in a `#prompt` inhibits further attempts to match that part of the line against both `#prompts` and `#actions` (so should be used only on a complete prompt, not on a part of it)

NOTE: Since a prompt may be followed by other text, when using regexp patterns in `#prompt` it is important not to end the pattern with $ (which matches the 'end of line')

Examples:

On MUME the prompt starts with either `o' or `*' and finishes with `>' So the regexp pattern `^[o\*].*>` will match all prompts and nothing else To do the same using normal patterns, one should use two patterns (and two `#prompts` ): `^o&1>` and `^*&1>`

On other MUDs of course the possible prompts will vary, so one must find which pattern (or patterns) will match all the possible prompts. If it also matches strings that are not prompts, care is required _not_ to run `#isprompt` in such cases.

Let's continue with the MUME example: using regexp patterns, a correct `#prompt` is:

#prompt %default ^[o\][^>]>= {#isprompt -1; #($prompt = "xyz " + attr “bold” + $prompt + noattr)}


Note that the pattern contains _two_ backslashes instead of one, as powwow unescapes regexp patterns. Also, `[^>]*>` is used instead of `.*>` to stop matching at the _first_ `>' (regexp by default would match the longest text possible, stopping at the _last_ `>' in the line)

The `#prompt` above correctly matches every MUME prompt, runs `#isprompt -1` on it (which declares that the prompt is as long as `$1` since in regexp patterns `$1` is the whole match, it is a good choice) then modifies the prompt in a custom way (puts it in bold then appends it to "xyz ")

Of course `#prompts` may do whatever one wants, but with a limitation: they must run `#isprompt` _before_ modifying the prompt, or unpredictable things could happen.

To have the same effect with normal patterns, the following would be needed:

#prompt >default1 ^o&1>= {#isprompt (2+.?$(1)); #($prompt = "xyz " + attr “bold” + $prompt + noattr)}

#prompt >default2 ^*&1>= {#isprompt (2+.?$(1)); #($prompt = "xyz " + attr “bold” + $prompt + noattr)}


The expression after `#isprompt` means "2 plus the length of `$1` " which is obviously the correct length, as `$1` does not contain `o' (or `*') and `>'.

Final note: If the prompt is longer than a whole line, it may be drawn incorrectly and may interfere with the input line (yep, it's a bug).

MUME players who happen to own a Valar+ character will find this useful too:

#prompt >default3 ^+&1>={#isprompt (2+.?$(1))} or, to use regexp patterns: #prompt %default ^[o\\+][^>]>={#isprompt -1}