1 P O W W O W 2 3 doc for version 1.2.16 4 last modified Oct 09, 2007 5 6INTRODUCTION 7 8 powwow is a client program, which replaces telnet for the lazy 9 mudder who wants some (only some?) extra features. 10 It is primarily designed for DikuMUDs, but nothing prevents its use 11 for other types of muds. powwow is based on another client, cancan, 12 and cancan was originally inspired by tintin (yet another client) 13 by Peter Unold (pjunold@daimi.aau.dk), but is entirely re-written. 14 powwow also implements the MUME remote editing protocol, which 15 enables you to edit texts on the mud using your own favourite 16 editor, several texts at once if you have a windowing terminal. 17 18STARTING POWWOW 19 20 Powwow maintains definition files where aliases, actions and 21 mud addresses are saved. Powwow is then called by: 22 23 $ powwow definition-file 24 25 (the $ above stands for your prompt, do NOT type it) 26 27 If the definition file doesn't exist (as the first time you 28 use powwow) you are asked for a host name and port number. 29 This will then be stored in the file. The file will be updated 30 every time you type '#save' or when powwow terminates. 31 The file is in plain text, so you can edit it if you want. 32 It makes sense to have one file for each mud you play, or for 33 each set of definitions you use in the same mud. 34 35 If the environment variable POWWOWDIR exists, that directory 36 is first searched for definition files and new files are 37 created there rather than in the current directory, unless 38 definition-file contains a slash ("/"). 39 40 The file 'Config.demo' is a demonstrative definition file provided 41 together with powwow to help you building your own configuration. 42 Look at it: there are many useful examples and non-trivial code 43 to fully use powwow. 44 45 You may also start powwow with: 46 47 $ powwow netaddress portnumber 48 49 but nothing will then be saved. 50 51 In alternative you can simply type: 52 53 $ powwow 54 55 and you will enter test-mode: you will be able to use internal commands 56 but you will need to start a session manually 57 (#connect main <address> <port>) if you want to connect to a MUD. 58 59 To solve the problem met in MUME, where you may have to try many 60 different servers to connect to the game, a fourth syntax has been 61 added: 62 63 $ powwow definition-file netaddress portnumber 64 65 With this syntax powwow reads settings from definition file, 66 but overwrites the old address with the newly specified one. 67 68 Note: If you have several sessions (different invokations) 69 with the same definition file active simultaneously, the 70 settings changed in one session can be overwritten by a change 71 in another session. 72 73QUITTING POWWOW 74 75 At any time, you can type #quit to exit from powwow. Be 76 careful, as #quit brutally closes the connection to the mud, 77 without renting your character. Normally, you want to log out 78 gracefully from the mud before doing that. If you wish to cut 79 your link manually, you can also press the break key on your 80 system twice (usually Control-C or DEL) (You must hit it twice 81 because hitting only once is used to stop command parsing - 82 see the bottom of this file). 83 84POWWOW TEST MODE 85 86 There are various ways to enter powwow test mode: 87 88 1) typing `powwow' from you command shell 89 (You will have to load your definition file manually if you need it, 90 using the following command: #load <save-file> ) 91 92 2) starting powwow with a definition file that does not contain 93 a '#host' line or contains a '#host' alone, without any address 94 95 3) starting powwow opening one or more MUD connections, 96 then closing them all. (You'll need to have #option quit 97 disabled or powwow will exit when closing the last connection) 98 99 Remember that to connect to a MUD from test mode you must use: 100 #connect main <address> <port> 101 102COMMAND CHAINING 103 104 Powwow allows you to type several commands on one line 105 separated by the ; character. If you want to use a semicolon 106 literally, prefix it by a backslash (\). (Backslashes must of 107 course be escaped too if used literally.) 108 109 Examples: 110 > n;get coins;s rapidly rescue some money 111 > say No beer? \;) semicolon must be escaped 112 113 In addition, you must also surround every list of commands by braces: 114 '{' and '}'. The only exception (as you can see from the example above) 115 is when you type multiple commands from keyboard: in that case, 116 and only in that, braces are not needed. 117 Also, if you want to use a { or } literally, prefix it with a backslash 118 as you do with semicolons. 119 120 Another use of semicolons is to send a <new-line> character to the MUD 121 you are connected to. Infact powwow sends a <new-line> every time it 122 meets a null command (0 chars) followed by a semicolon. 123 124 Examples: 125 > press <return> only: send a <new-line> 126 > ; press ; and then <return>: same effect 127 > ;; send two <new-line> 128 > ;;; three <new-line> ... 129 130 Of course multiple <new-line> are considered as multiple commands, 131 so you usually have to surrond them with braces. If directly typed 132 from keyboard, the braces are optional. 133 134 > {} do nothing 135 > {;} send a <new-line> 136 > {;;} send two <new-line> 137 > {;;;} and so on... 138 139 The verbatim mode disables this special meaning of semicolons and 140 braces, and the #quote command lets you switch between verbatim and 141 normal mode. 142 143COMMAND CONTINUATION 144 145 Long lines can be continued by ending each intermediate line with a 146 backslash (\). This way long and complicated aliases can be written 147 a somewhat readable format. For example: 148 149 #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} 150 151 Could be written (somewhat) more legibly as: 152 153 #al drau={\ 154 #send ("get tail "+$hcon);\ 155 #send ("get fur "+$hcon);\ 156 #send ("get vial "+$hcon);\ 157 #send ("get tarragon "+$hcon);\ 158 put tail kit;\ 159 put fur kit;\ 160 put vial kit;\ 161 put tarragon kit\ 162 } 163 164 Note that when powwow saves your aliases (e.g. you leave #file defined) 165 that it will not preserve this formatting, so it is most useful if 166 you use a file that is not saved over on exit. For example, if 167 you use a single configuration file that calls several smaller 168 configuration files that are grouped by similar intent, like having 169 an xp counter script, a prompt script, etc. 170 171SPECIAL COMMANDS: ALIASES AND ACTIONS 172 173 Powwow parses all lines beginning with the character '#' as 174 special commands. To send a line that begins with '#' itself, precede 175 it with a backslash. The commands are case-sensitive. 176 Commands can be abbreviated as much as you want. 177 ----------------------------------------------------------- 178 Alias definition 179 #alias [name[=[command]]] 180 181 Aliases are abbreviations for longer, frequently used commands. 182 As all powwow commands, they are only recognized at the beginning 183 of a line or directly after a semicolon, an open or closed brace. 184 When an alias is used, the first word following the alias name 185 is placed in the variable $1, the second in $2, etc... up to $9. 186 also, the whole string following alias name is placed in $0. 187 188 Then, before executing <command>, every $n in <command> is replaced 189 by its contents. 190 191 Example: 192 #alias summ=cast 'summon' $0 (then "summ thor" is replaced by 193 "cast 'summon' thor") 194 #alias cs=cast '$1' $2 ("cs summon thor" is expanded to 195 "cast 'summon' thor") 196 #alias summ (lets you edit the definition of summ) 197 #alias summ= (removes the alias summ) 198 #alias (display all defined aliases) 199 #alias ws={wake;stand} (note that you must use braces) 200 201 As noted above, aliases are saved automatically if you started powwow 202 with a file name as argument. 203 Aliases can contain other aliases, and an alias can also contain itself 204 (be careful, or powwow will enter a long - but not infinite - loop) 205 Aliases are not expanded in verbatim mode. 206 207 Where aliases contain other aliases, one or more '\' can be prepended 208 to $n to delay text substition or to use the symbol $n literally. 209 210 Example: 211 #alias ac=#alias $1=cast '$2' \$0 212 (then "ac sm summon" will give you a new alias 213 "#alias sm=cast 'summon' $0") 214 215 #alias \==score 216 (this defines = as an alias for 'score', Note that you must 217 escape the first = to force powwow to consider it literally) 218 219 #alias \`=#history $0 220 (this defines \ as an alias for '#history'. Note that you must 221 use ` to escape the \ . Just doing \= would escape the = ) 222 223 Aliases starting with `#' are allowed and do work, 224 but cannot override any special command. 225 ----------------------------------------------------------- 226 Automatic command execution triggered on output 227 #action [[<|=|>|%][+|-]label] [{pattern | (expression)}=[command]] 228 229 When 'pattern' is found in a line from the remote host, the 230 'command' is automatically executed. If the pattern contains $n, 231 powwow matches one word of the remote line and puts it in the 232 variable $n. If the pattern contains &n, powwow matches a string 233 (possibly more than one word) of the shortest possible length 234 from the remote line and puts it in the variable $n. 235 236 As in aliases, $n can be from $1 to $9. NOTE: $0 is a variable as well, 237 but #action automatically places in it the whole line from remote host. 238 As well, &n can be from &1 to &9. 239 240 Warning: powwow does NOT print on screen lines from MUD that are 241 intercepted with an #action. So if you want to print them, you 242 must explicitly use a #print or set the #option +autoprint 243 (the help on #print and #option is below in this text) 244 If you want to intercept a prompt, use #prompt instead of #action. 245 (the help on #prompt is near the end of this file) 246 247 If the first character of the pattern is ^ (caret), the match 248 will only be possible at the beginning of a line. 249 The match is case-sensitive. 250 If 'label' is specified, the action is labeled; otherwise it is 251 numbered. 252 253 If an <expression surrounded by parentheses> is used insted of pattern, 254 powwow evaluates the expression with the inline calculator (see below) 255 and then uses the result as pattern. 256 257 Examples: 258 #action ^You are hungry=eat bread 259 #action ^You are hungry= (removes the action) 260 #action ^$1 hugs you={#print;kiss $1} 261 #action ^$1 says &2=say $1 said $2 (note you must use $, not & 262 after the =) 263 #action Jehova={#print;say Who said that? Stone him!} 264 265 Labeled actions: 266 > means define, < means delete, = is edit, + is turn on, - is turn off. 267 Also, >- means define and turn off, while >+ means define and turn on 268 ( > alone is the same as >+ ) 269 270 #action >fount ^There is a fountain here={#print;drink water} 271 (named action) 272 #action -fount (turns off action) 273 #action +fount (turns it back on) 274 #action =fount (lets you edit it) 275 #action <fount (removes action) 276 277 #action >-loot is dead! R.I.P.={#print;get all from corpse} 278 (define and turn off the action) 279 280 #action >joke ("^$1 says '&2;)'")= wink $1 281 (you must either use this syntax or escape the 282 ; to force it to be considered literally) 283 284 #action >argh ^$1 tells you 'hello \`=tell $1 I heard you 285 (as in #alias, \ must be followed by ` when you 286 need the \ to be followed by a special char 287 and you do not want this char to be escaped) 288 289 If you have compiled powwow with -DUSE_REGEXP and use % instead of > 290 you define an action that uses an Extended POSIX regexp to match 291 instead of the standard matcher. 292 293 #action %first ^([[:alpha:]]+) ([[:digit:]]+)=#print $2 counted $3. 294 (matches abc 123) 295 296 Note that if the pattern starts with '(', it is evaluated, which means 297 that a regexp that starts with '(' has either to be surrounded by 298 ("...") or to be prepended by a backslash. 299 Also note that powwow requires parentheses to be balanced: 300 for example, \(.+|) would be a valid regexp pattern as the backslash 301 gets removed by the unescaping, but powwow will choke on it 302 as the first parenthesis is escaped while the second is not. 303 304 #action %second ("(..+)-\\1")=#print Double $1 305 (matches xyz-xyz) 306 #action %third \(..+\)-\\1=#print Double $1 307 (same as above) 308 For regexp actions, $0 = the line, $1 = the whole match and $2... 309 contain the submatches. 310 311 Actions and aliases can run other powwow commands, including 312 #action and #alias. 313 Example: 314 #alias calc=#! echo '$0' | bc -l 315 #alias hungryon=#action ^You are hungry=eat bread 316 317 As with aliases, additional \'s can be prepended to $n to 318 delay text substitution in actions. 319 Example: 320 #action >reply ^$1 tells you={#print; #alias reply=tell $1 \$0} 321 ----------------------------------------------------------- 322 323ACTION GROUPS 324 325 Groups allow related triggers to be enabled and disabled together 326 using a single command, instead of toggling them all on or off 327 individually. To put actions in to a group specify the group name 328 after an '@' when the action is defined. For example: 329 330 #action >+auto-ride@non-pk ZBLAM! A &1 doesn't want you={#print;stand;ride} 331 332 Would create the action auto-ride in the non-pk group. Then if you 333 wanted to toggle off all non-pk actions, you could do it using: 334 335 #group non-pk off 336 337 And then later to turn them back on, use: 338 339 #group non-pk on 340 341MISSING: #PROMPT 342 343 There is another special command quite similar to #action: 344 #prompt [[<|=|>|%][+|-]label] [{pattern | (expression)}=[command]] 345 346 You will need to use it only if you want to mess with the prompt 347 that your MUD sends, which is often not needed. Also, to use it 348 you need to understand exactly how powwow recognizes prompts, 349 so the description is considered an advanced topic and is placed 350 near the end of this file, in the "ADVANCED TOPIC: #PROMPT" section. 351 352MISSING: SUBSTITUTION AND UNESCAPING 353 354 Also, only intuitive definitions of substitution, delayed substition 355 and escaping/unescaping have been given so far. If you want the real, 356 rigorous thing, read the "ADVANCED TOPIC: SUBSTITUTIONS AND UNESCAPING" 357 section near the end of this file. That section also explains 358 `just in time' substitution, not yet introduced. 359 ----------------------------------------------------------- 360 361SPECIAL COMMANDS: ALL OTHERS 362 363 This is the rest of #commands recognized by powwow. 364 ----------------------------------------------------------- 365 Toggle verbatim mode 366 #quote [on | off] 367 368 In verbatim mode, no alias expansion takes place and 369 semicolons, escapes, braces and ` are sent as typed, 370 unless the command line begins with a #, so you can still issue 371 powwow - specific commands. 372 This is useful if you want to paste a text from an editor into 373 a powwow session. 374 Type #quote to turn on the verbatim mode, and type #quote again 375 to turn it off. 376 ----------------------------------------------------------- 377 Show/execute commands in history 378 #history [number] 379 380 #history alone shows you the last commands in history, up to the number 381 of lines in your screen. 382 #history -n shows the last n commands in history, and 383 #history n executes the n-th command of the history. 384 385 Recursive #history commands (i.e. an #history <n> calling itself or 386 another #history <n>) are allowed only up to levels of 128 recursions. 387 388 Example: 389 390 #history 1 (repeat last command) 391 ----------------------------------------------------------- 392 Add a text or expression to word completion list (not to history) 393 #add {text | (expression)} 394 395 #add puts the text or result of expression (calculator is used to 396 evaluate the expression) in the word completion list. 397 Useful if used together with #action. 398 Example: 399 400 #action >reply ^$1 tells you={#print;#add $1} 401 (from now on, you can use TAB to complete that name) 402 ----------------------------------------------------------- 403 Put a text or expression into history (and to word completion list) 404 #put {text | (expression)} 405 406 #put puts the text or result of expression (uses calculator) in the 407 history, so that you can use cursor-up key to recall the text as if 408 typed from keyboard. 409 Also, you can execute the text using the #history command. 410 Example: 411 412 #action >safeflee ^You flee head over heels.= 413 {#print;#put #print You have already fled away!} 414 415 (If you type 'flee' from keyboard, you can keep trying to flee using 416 cursor-up (which gets the last command in history) and <RETURN> key. 417 When you finally manage to flee, the message above is put in history, 418 so that further attempts to flee do not lead you again in danger) 419 ----------------------------------------------------------- 420 Bind keys to enter commands 421 #bind [edit | name [sequence][=[command]]] 422 423 You can bind most function keys and control keys to enter a command 424 for you when the key is pressed. Also, you can redefine a key already 425 used for an editing function (such as the arrow keys). 426 'name' is the label of the key you want to define; you can just use 427 what is written upon it. When defining a new key binding, you will 428 be asked to press it so powwow can record the control sequence 429 your terminal sends. 430 If you want, you can specify the control sequence directly in the #bind 431 command instead of having to press the key on your keyboard. 432 433 Examples: 434 435 #bind (lists all user key bindings) 436 #bind edit (lists all line editing keys) 437 #bind f1=recite scroll (you'll have to press f1 then) 438 #bind f1=cast 'sanctuary' (change existing definition) 439 #bind f1 (lets you edit the definition) 440 #bind f1= (removes the key) 441 #bind f1 [[A=cast 'heal' (also tell powwow that f1 on your 442 keyboard sends ESC [ [ A, so you 443 do not have to press it) 444 445 NOTE: if there is already something on your input line, powwow 446 does not ruin it when you press f1 (or any other #bind), but executes 447 the command you want and then shows you again the input line. 448 449 #bind f5=&prev-line (&prev-line is one of the reserved commands for 450 line-editing functions, see bottom 451 of this file) 452 #bind Up=u (Up is an editing key, but can be redefined) 453 454 By default, the vt100 numeric keypad is partially used to walk around 455 with: 456 Key string sent 457 2 s 458 3 d 459 4 w 460 5 exits 461 6 e 462 7 look 463 8 n 464 9 u 465 466 The reserved names that powwow identifies as line-editing functions 467 are at the end of this file, together with the default keys used for 468 them. 469 470 Remember that ALL keys can be redefined... 471 ----------------------------------------------------------- 472 Change the keyboard sequence associated to an existing key binding 473 #rebind name [sequence] 474 475 If you just want to change the control sequence of a binding, but not 476 its name or its effect, you can just tell powwow to 'rebind' it. 477 If #rebind is invoked with only the name of a binding, you are asked 478 to press the key you want to rebind. 479 Of course, you will not be asked to press the key if you specify 480 its control codes in the #rebind command. 481 Examples: 482 483 #rebind f1 ^[OP (tell powwow that your f1 key sends ESC O P 484 and not ESC [ [ A) 485 #rebind f1 (you are asked to press again f1, useful if you 486 changed terminal in the meanwhile) 487 ----------------------------------------------------------- 488 Change the keyboard sequence of all existing key bindings 489 #rebindall 490 #rebindALL 491 492 #rebindall runs #rebind on most key bindings (skips trivial ones like 493 ^A, ^B, etc.), asking you to press each corresponding key. 494 495 #rebindALL does the same, but for really every key binding. 496 ----------------------------------------------------------- 497 Execute a key as if pressed on keyboard 498 #key name 499 500 If 'name' is the label of one of the key defined with #bind, 501 (see above) #key executes the corresponding command. 502 503 Example: 504 If you have already typed 505 #bind f1=cast 'heal' 506 507 At any time, then, you can either: 508 - Press your f1 key on you keyboard 509 - Execute the command "#key f1" 510 and powwow will execute the command "cast 'heal'" for you. 511 512 Using #key, for example, can be useful from inside an 513 #alias or #action, since powwow cannot press f1 for you. 514 515 Since 1.1.5, powwow allows #key also for editing functions. 516 If you have already 517 #bind Up=&prev-line 518 and you execute 519 #key Up 520 powwow will do what you expect: step to the previous line in history. 521 522 Warning: powwow does not distinguish at all between a real key pressed 523 on the keyboard and one faked with #key, so commands executed with #key 524 will also be written in the #record file. 525 526 ----------------------------------------------------------- 527 Execute an editing function as if pressed on keyboard 528 #keyedit function 529 530 If 'function' is the name of one of the reserved commands 531 for line-editing functions, #keyedit function will run it. 532 533 For example, if you already have 534 #bind Up=&prev-line 535 the following are all equivalent: 536 * pressing the key Up on your keyboard 537 * executing #key Up 538 * executing #keyedit &prev-line 539 540 Anyway, if you type #key or #keyedit directly from the keyboard 541 the effect is slightly different, as you have to press ENTER 542 to run them and the function &enter-line (which is executed by ENTER) 543 has a few side effects. 544 ----------------------------------------------------------- 545 Clear aliases, actions or what you specify 546 #reset {all | name of a list} 547 548 Argument: Effect: 549 all clear everything (apply all lines below) 550 alias clear all aliases 551 action clear all actions 552 bind clear all key bindings and restart with default 553 settings. Note that also editing keys are resetted 554 to default function. 555 at clear all delayed commands 556 in (same thing) 557 mark clear all markers 558 prompt clear all prompts 559 var clear all variables 560 ----------------------------------------------------------- 561 Mark certain output 562 #mark [pattern[=[attribute]]] 563 564 This command highlights a part of a line in your output in the way you 565 choose (if your terminal supports it). 566 See the section "ATTRIBUTES: COLORS AND OTHER HILIGHTINGS" 567 about the syntax of attributes. 568 569 Wildcards are allowed in the pattern, and syntax is very similar to 570 #action: $ matches a single word, & matches any string. 571 572 Examples: 573 #mark Sizzler=bold (mark `Sizzler' in bold) 574 #mark Sizzler (lets you edit the above definition) 575 #mark Sizzler= (Sizzler is no longer put in bold) 576 #mark (lists all markers) 577 #mark {&}=inverse (mark in reverse any string in { } 578 note that also the { } are highlited) 579 #mark ^You=yellow (mark `You' in yellow only if it appears 580 at the beginning of a line) 581 #mark \^=on blue (mark a literal ^ ) 582 ----------------------------------------------------------- 583 #module [module name] 584 585 This loads a shared library module by name, if supported by your system. The 586 name of the module should be included in the documentation that came with the 587 powwow extension, for example to load the perl module you would use: 588 589 #module perl 590 591 Which gives you the perl command that can be used like: 592 593 #perl powwow::exec( "say it is " . scalar(localtime()) ) 594 595 The commands added and their syntax varies depending on the module. 596 ----------------------------------------------------------- 597 Set/show priority for new actions/marks 598 #nice [{number | (expression)} [command]] 599 600 When #nice is 0 (default) powwow puts new actions at the bottom of the 601 action list (and same thing for marks). If you want to put new 602 actions/marks in another point of the list, just set #nice to the 603 corresponding value: 604 605 If you specify a command after 'number', the new #nice value is used 606 only for that command, then the old value is restored. 607 608 Examples: 609 610 #nice 12 (tells powwow to put new actions/marks in the 12th 611 (place of the list) 612 613 #nice 4 #mark Grizzly=red on blue (put the mark in the 4th place of 614 the list) 615 616 Note that #nice works only for new actions/marks: if an action/mark 617 is already defined, you cannot change its place in the list. 618 ----------------------------------------------------------- 619 Input highlighting 620 #hilite [attribute] 621 622 This sets the attribute of your entered text to the given attribute. 623 Just #hilite turns it off. 624 See "ATTRIBUTES: COLORS AND OTHER HILIGHTINGS" below for more syntax. 625 ----------------------------------------------------------- 626 Set standard colours 627 #color [attrib] 628 629 (This command exists only if BUG_TELNET is defined, to cope with 630 deficiencies of NCSA telnet 2.2) 631 Set your standard foreground and background to the colours you specify. 632 #color returns to the default colors for your screen 633 ----------------------------------------------------------- 634 Capture output to file 635 #capture [[>]filename] 636 637 This captures all output from the main MUD connection and your typed 638 commands to a local disk file. To close the file and end the 639 capturing, type #capture without argument. 640 If the filename starts with a '>', new text will be appended to the 641 end of the file instead of overwriting it. 642 You can only capture output to one file at a time. 643 Example: 644 > #capture message 645 > look at board 646 > #capture 647 648 It is possible to capture in the #capture file even text that you have 649 _already_ received: see #setvar buffer. 650 ----------------------------------------------------------- 651 Record typed commands to file 652 #record [filename] 653 654 This records all text typed from keyboard to a local disk file. 655 (output from remote host is not recorded) 656 To close the file and end the recording, type #record without argument. 657 You can only record typed text to one file at a time, but #capture and 658 #record can be active at the same time on different files. 659 Example: 660 > #record walk-home 661 > n;e;e;u;n;w;s 662 > open door 663 > s 664 > close door 665 > sleep 666 > #record 667 ----------------------------------------------------------- 668 Capture output to file, with timestamps 669 #movie [filename] 670 671 This is similar to #capture, but adds timestamps to each line 672 received from the main MUD connection or typed from the keyboard, 673 to allow replay at correct speed. 674 The program `powwow-movieplay' for replay is included with powwow sources. 675 Usage: `powwow-movieplay <filename>' 676 To convert a movie to plain ASCII, the program `powwow-movie2ascii' 677 is included too. 678 Usage: `powwow-movie2ascii <infile> <outfile>'. 679 680 It is possible to capture in the #movie file even text that you have 681 _already_ received: see #setvar buffer. 682 ----------------------------------------------------------- 683 Execute a shell command 684 #! command 685 686 Executes a command using /bin/sh. Powwow waits until your shell 687 finishes, but you can put jobs in the background with & as usual. 688 Example: 689 > #! who | sort | less 690 > #! nethack 691 > #! xbiff & 692 693 Note that semicolons, escapes and braces need to be escaped if they 694 are to be sent to the shell. 695 If your shell has job control, you can also suspend powwow 696 with ^Z as usual. 697 ----------------------------------------------------------- 698 Put a string in the edit buffer automatically 699 #prefix [string] 700 701 Each new line you type will automatically begin with the prefix string. 702 You can of course edit or delete the inserted string as usual. To 703 remove the prefix, just issue a #prefix command without arguments. 704 This is handy when you are talking to someone, for example. 705 > #prefix tell arthur 706 ----------------------------------------------------------- 707 Help 708 #help [keys | math | command] 709 710 Shows a list of powwow's commands. 711 '#help keys' shows the editing keys. 712 '#help math' show help on inline calculator. 713 You can also have help on specific commands, using for example 714 '#help alias' or in general '#help <command-name>'. 715 A help file is needed and provided for this last feature of #help, 716 and powwow will look for the file "powwow_help" in the directory 717 specified by the environment variable POWWOWHELP. If this variable 718 does not exist, powwow looks in current directory. 719 ----------------------------------------------------------- 720 Command repetition 721 #n command 722 723 This repeats the command n times. Example: 724 > #5 buy bread (buy five breads) 725 726 727 Alternatively, you can use this syntax to repeat a command n times: 728 #do (expr) command 729 730 In this case, powwow evaluates the expression, and uses the result 731 as counter. 732 Example: 733 > #do (3*8) north (go north 24 times) 734 ----------------------------------------------------------- 735 Iterate a command 736 #while (expression) command 737 738 This syntax repeats a command while expression (evaluated with 739 calculator) keeps true. (see below for help about calculator) 740 As with #alias and #action, the $n and @n in command are 741 replaced by their values. (Even if you can, using @n after the = 742 in #action and #alias is useless, because you have no way to 743 assign them a non-zero value. This is the reason why we did not talk 744 about them in the #alias and #action section) 745 746 Example: 747 748 #while (@0<13) {read @0;#(\@0++)} read messages 0-12 749 As you can see, the last @0 is escaped to avoid it to be 750 substituted with its value. (We want to increase the variable!) 751 ----------------------------------------------------------- 752 Iterate a command 753 #for ([init];check;[loop]) command 754 755 Directly copied from C language, this command evaluates 'init' 756 with calculator (if specified), then repeats the following cycle: 757 1) evaluate 'check', if result is 0 (false) stop repetition 758 2) execute 'command' 759 3) evaluate 'loop' (if specified) 760 4) restart from 1) 761 762 As with #while, #for performs the parameter substitution in 'command', 763 so the only significative difference between #while and #for is that 764 #for allows you to execute an initialization before the repeat cycle. 765 766 Example: 767 768 #for (@1=32; @1<=47; @1++) read @0 (read messages 32-47) 769 ----------------------------------------------------------- 770 Branch execution command 771 #if (expression) command1 [; #else command2] 772 773 Evaluate the expression: if result is 'true' execute command1, 774 otherwise (if there is an #else) execute command2. 775 If expression is false and there is no #else, execute nothing. 776 remember that you must use braces {} if command1 or command2 777 contain more than one instruction. 778 779 Note that nested #if-#else are allowed, and that #if-#else itself 780 is not a multiple command. 781 782 WARNING: using an alias for #if is very dangerous and will cause 783 powwow to make confusion when the full #if-#else syntax is used. 784 ----------------------------------------------------------- 785 Automapping control 786 #map [-[number] | walksequence] 787 788 With no argument, "#map" shows the map of the directions you 789 travelled up to now. "#map -" clears the last number of steps 790 from the map. 791 792 Example: 793 #map (displays "#current map: e3su" after above walk) 794 #map -1 (leaves the map as "esss") 795 #map - (clears the whole map and starts fresh) 796 #map nsssue (add the list of directions to map) 797 ----------------------------------------------------------- 798 Retrace steps 799 #retrace [number] 800 801 This command walks you in the reverse direction of the last 802 number of steps. If number is 0 or left blank, you walk all 803 the way back to where automapping started. 804 ----------------------------------------------------------- 805 Explicitly execute a speedwalk 806 #speedwalk [walksequence] 807 808 This command can be used to execute a speedwalk sequence even 809 if you have the speedwalk option disabled. This is useful if you 810 do not like to have typos evaluated as speedwalk commands but still 811 want to be able to easily execute a speedwalk. 812 ----------------------------------------------------------- 813 Connect initialization string 814 #init [=[command]] 815 816 This command sets up the initialization string to send to 817 the host on establishing a connection. 818 819 Example: 820 #init (shows the string) 821 #init ={#identify;#speedwalk} (sets the string) 822 #init = (clears the whole string) 823 ----------------------------------------------------------- 824 Identify as an editing client 825 #identify [startedit [endedit]] 826 827 This command sends an identification string to the server, to 828 indicate that the client supports editing functions. It is 829 best attached to an action trigged by a string in the login 830 screen, but can also be entered by hand. 831 This command must be issued for the cooperative editing to work 832 on servers that support it (currently only MUME). 833 The startedit/endedit parameters are commands issued when an editing 834 session starts/ends (for changing your title, emoting etc). 835 836 Example: 837 838 #action >mume *** MUME=#identify 839 #identify foo bar 840 (where foo and bar are aliases that do something useful) 841 ----------------------------------------------------------- 842 Identify as a IAC GA compliant client 843 #request prompt 844 845 This command sends an identification string to the server, to 846 indicate that the client supports (and wants) the special sequence 847 IAC GA at the end of each prompt. This helps the client 848 to automatically detect the prompt, and can be used as alternative 849 to #prompt / #isprompt if all you want with the prompt is detecting 850 it (and not altering it) 851 852 BIG WARNING: 853 this is experimental and not tested! 854 855 Example: 856 857 #action >mume *** MUME={#print;#identify;#request prompt} 858 #request prompt 859 ----------------------------------------------------------- 860 List all editing sessions 861 #edit 862 863 This command shows your active editing sessions, with a brief 864 description and their number. 865 ----------------------------------------------------------- 866 Cancel an editing session 867 #cancel [number] 868 869 Without an argument, all editing sessions are cancelled; 870 otherwise, only the given session is cancelled. The corresponding 871 editor processes are brutally killed. 872 ----------------------------------------------------------- 873 List/turn various options on/off 874 #option [[+|-|=]option-name] 875 876 Currently available option names are: 877 exit, history, wrap, compact, debug, echo, info, keyecho, 878 speedwalk, wrap, autoprint, buffer, reprint, sendsize, 879 autoclear 880 881 #option +name turns an option on 882 #option -name turns it off 883 #option name toggles it 884 #option =name reports its status 885 886 ------------- 887 #option exit 888 889 If the `exit' option is on, powwow automatically quits when the last 890 connection is closed. Otherwise, to quit powwow you need to manually 891 type `#quit' 892 ------------- 893 #option history 894 895 With `history' option on, powwow writes into your savefile also 896 all your commands in history 897 ------------- 898 #option words 899 900 With `words' option on, powwow writes into your savefile also 901 your word completion list 902 ------------- 903 #option compact 904 905 Normally, powwow does not touch the prompts on screen while you play. 906 In `compact' mode, instead, lines containing only a prompt are deleted 907 when further messages arrive from the remote host. 908 909 WARNING: this command works correctly only if you have #prompts which 910 correctly run #isprompt. Otherwise it may occasionally erase 911 some lines from the screen. 912 ------------- 913 #option debug 914 915 Normally, powwow does not print on screen the command lines it 916 executes. When `debug' is on, every line executed by powwow is also 917 echoed on screen, so that you can check if your code works correctly 918 (warning: this prints LOTS of lines on your screen) 919 ------------- 920 #option echo 921 922 Normally, powwow echoes on your screen each command sent to remote 923 host but not directly typed (example: aliases and actions sending text 924 to the MUD). When `echo' is off, such commands are still sent to host, 925 but not echoed on screen. 926 ------------- 927 #option info 928 929 Normally, powwow prints on screen some messages each time you 930 define/edit/delete an #alias, #action, #bind and similar. 931 When `info' is off, those messages are not typed at all. 932 (But errors are still printed on screen) 933 ------------- 934 #option keyecho 935 936 Normally, powwow echoes on your screen the commands sent to remote host 937 when you hit a key associated to a #bind. When `keyecho' is off, such 938 commands are still sent to host, but not echoed on screen. 939 ------------- 940 #option speedwalk 941 942 With `speedwalk' on, a command consisting of only lowercase 943 n, e, s, w, u, d and numeric digits is considered to be a 944 walk sequence. The numeric digits specify the number of 945 times to repeat the direction immediately following. 946 947 Example: 948 esssu (walk east, 3 south, up) 949 e3su (same as above) 950 ------------- 951 #option wrap 952 953 Normally, powwow wraps words that would have been cut by the right 954 margin to the next line. This command lets you turn it off and on. 955 ------------- 956 #option autoprint 957 958 If `autoprint' is on, powwow prints lines matched by an #action 959 even without an explicit #print. 960 ------------- 961 #option sendsize 962 963 Usually powwow does not send the window size to the MUD unless asked. 964 If you want to send the window size automatically upon connecting, 965 you may enable this option. 966 ------------- 967 #option autoclear 968 969 Powwow normally erases the input line before executing commands 970 from spawned programs, but that is slow and causes flicker. 971 If autoclear is disabled flicker reduces to minimum, 972 on the other hand spawned programs must then execute #clear 973 before sending anything to screen. 974 ------------- 975 #option reprint 976 977 If `reprint' is on (off by default), powwow prints again commands 978 sent to the mud but not yet executed. 979 WARNING: it works only if you use #prompts which correctly run 980 #isprompt. 981 982 ++++ example: ++++ 983 *>look 984 south 985 down 986 987 The High Path 988 989 *>Path Climbing a Hill 990 991 *> 992 Alas, you cannot go that way. 993 994 *> 995 ++++ becomes: ++++ 996 *>look 997 south 998 down 999 1000 The High Path 1001 1002 *>(south) 1003 Path Climbing a Hill 1004 1005 *>(down) 1006 Alas, you cannot go that way. 1007 1008 *> 1009 ----------------------------------------------------------- 1010 Show current version 1011 #ver 1012 1013 Displays the current version, some compile options and (if 1014 your compiler supports it) when powwow was compiled. 1015 ----------------------------------------------------------- 1016 Multiple connections handling commands 1017 #connect [session-id [initstr] [host port]] 1018 connect a new session / list sessions 1019 #snoop session-id toggle output display for session 1020 #zap session-id disconnect a session 1021 ##<session-id> set <session-id> as default session 1022 ##<session-id> command execute command on <session-id> session 1023 1024 No docs here. If multiplaying is allowed on you MUD (and many 1025 do NOT allow) you can experiment a little to find how they work. 1026 Or you can open two connections to two different MUDs :) 1027 ----------------------------------------------------------- 1028 Spawn an external program 1029 #spawn session-id command 1030 1031 Creates a new session, connected to a shell command instead of a MUD. 1032 Writing to ##<session-id> sends data to the command's standard input, 1033 while the command's standard output is executed as if typed 1034 from keyboard. Useful if you are a programmer and you want to create 1035 very complex filters or robots, for which #actions are too limited. 1036 Command's standard output *MUST* terminate with a newline ('\n') in 1037 order for powwow to execute it. 1038 You can send multiple commands at once terminating each of them 1039 by either a semi-colon ';' or a newline '\n', except for the last one 1040 which (I repeat) *MUST* terminate with a newline. 1041 1042 You can close these sessions with #zap and list them with #connect 1043 as usual. 1044 1045 Depending on how lazy you are, you can choose two different ways 1046 to have spawned programs print to screen: 1047 1048 The first is automatic, but slow: with `#option +autoclear' 1049 powwow clears the input line before executing every line received 1050 from the program. This is of course slow and causes flickering. 1051 1052 The second is more complex, but faster and reduces flickering to the 1053 minimum: set `#option -autoclear' from the beginning, then have 1054 the program execute `#clear' before printing. 1055 ----------------------------------------------------------- 1056 Exit from powwow 1057 #quit 1058 1059 Very little to say here. Just remember that #quit brutally 1060 closes all mud connections that are still open, without 1061 renting your characters. Quite likely, you want to rent them all 1062 before quitting. 1063 ----------------------------------------------------------- 1064 Set definition-file and save settings to it. 1065 #save [definition-file] 1066 1067 Useful after you write large chunks of code. 1068 Remember anyway that powwow automatically saves the settings 1069 before exiting. 1070 1071 #save actually writes settings to a temporary file and overwrites 1072 the definition file only if write succeeds. This is to avoid wiping out 1073 definition file in case of `disk full' or other errors. 1074 ----------------------------------------------------------- 1075 Set definition-file and load settings from it. 1076 #load [definition-file] 1077 1078 Useful if you want to undo the changes in your settings. 1079 1080 NOTE: current settings are completely erased before actually loading 1081 from file. In case of errors, powwow reloads the default editing keys. 1082 1083 If you just want to add the contents of a file to your current settings 1084 use #exe <filename instead of #load. 1085 ----------------------------------------------------------- 1086 Set/show/clear definition-file name 1087 #file [=[definition-file]] 1088 1089 As default, the definition-file is the one loaded when you start 1090 powwow. Remember that powwow automatically saves your settings to it 1091 before exiting. If you want to disable this autosave, use #file = 1092 ----------------------------------------------------------- 1093 Various commands: 1094 #net show amount of data transmitted to and received from 1095 the remote host. 1096 #cpu show the CPU time used by powwow. 1097 (if powwow does not find the symbol CLOCKS_PER_SEC 1098 defined at compile time, the result may not be in 1099 seconds...) 1100 #time show current time/date. Useful if you want to use #at. 1101 1102 #beep ring your terminal's bell (like #print (*7)) 1103 ----------------------------------------------------------- 1104 List/delete/define/edit delayed commands 1105 #at [label [(time-expression) [command]]] 1106 or 1107 #in [label [(delay in millisec.) [command]]] 1108 1109 If you want to tell powwow to execute the command 'kill wolf' 1110 2 seconds after you type it, use this command: 1111 #in attack (2000) kill wolf 1112 Let's explain the command: 1113 'attack' is a label, exactly as in #actions, and is used only to have 1114 a quick reference to the delayed command; 1115 (2000) means wait 2000 millisec., i.e. 2 seconds; 1116 'kill wolf' simply executes kill wolf, as if typed from keyboard. 1117 1118 Of course, you can use an expression (as complex as you like) 1119 instead of the number in parentheses, 1120 and the command can also be an alias, internal command or even 1121 another #at or #in. (of course you can use multiple commands by 1122 placing them in { } ) 1123 1124 If you do not specify the command, powwow assumes the label is already 1125 defined, and changes its delay. 1126 A delay less than zero means the delayed label is disabled, 1127 but still in powwow's memory, similar to what happems when you 1128 turn off an #action. 1129 A delay of zero deletes the delayed label. 1130 1131 If you specify only a label, powwow lists it. 1132 If you specify nothing, all delayed labels are listed. 1133 1134 The #at command is nearly equal to #in, but assumes the expression 1135 in ( ) is a time. For example (114520) means 11:45:20 , 1136 and ("114520") is the same. 1137 After evaluating the time, powwow converts it into a delay, 1138 and places the delayed label in the same list of #in. 1139 NOTE: it is not possible to delete a delayed label using #at, 1140 since (0) means midnight. 1141 One more thing: it is not possible do define disabled labels using #at, 1142 because a time < 0 is an error, and a time < current-time is assumed 1143 to be refering to the following day. 1144 1145 Last note: after executing a delayed command, powwow does not delete 1146 it, but simply disables it. 1147 ----------------------------------------------------------- 1148 Disable all delayed commands 1149 #stop 1150 1151 All active delayed commands are set to 'disabled', but are not deleted 1152 from memory. Useful to stop infinite loops due to self-reactivating 1153 delayed commands. 1154 ----------------------------------------------------------- 1155 Set save file options 1156 #option [none]|[words][history] 1157 1158 Controls wether command history and completion words shall be saved 1159 in the save file. 1160 1161 Without arguments, #option displays the current settings. 1162 To turn off both words and history, use #option none; otherwise 1163 use #option followed by words and/or history. 1164 1165 ----------------------------------------------------------- 1166 Evaluate expression with calculator, and trash result. 1167 # (expression) or #(expression) 1168 1169 ----------------------------------------------------------- 1170 Print a text or result of an expression on screen. 1171 (does NOT send it to the MUD) 1172 #print [< | !][text | (expression)] 1173 1174 If a string is specified, powwow simply prints it on screen. 1175 If an expression is specified, powwow uses the inline calculator 1176 to evaluate it, and then prints the result. 1177 1178 If a #print without arguments is found, powwow prints the value 1179 of the variable $0 (this is a special feature of #print, and is not 1180 present in #exe, #send, #emulate or #var). 1181 This is usually used to print a line from remote host that was 1182 intercepted by an #action, in fact #action places the whole line in $0 1183 1184 If < precedes the text or expression, #print assumes text (or result 1185 of expression) to be name of a file, and displays the contents of 1186 that file. 1187 1188 Instead if ! precedes the text or expression, #print assumes text (or 1189 result of expression) to be a Bourne shell command, whose output is 1190 displayed. 1191 1192 Example: 1193 1194 #action >disint ^&1 disintegrates &2=#print $1 DISINTEGRATES $2 1195 put the text in upper case 1196 #action >disint ^&1 disintegrates &2=#print ($(1)+" DISINTEGRATES "+$(2)) 1197 same thing, but using calculator 1198 1199 #print <mytext display a text on screen 1200 #print !("more mytext") same thing, but uses 'more' 1201 as text viewer and alternate syntax 1202 #print (@-7) print value of variable on screen 1203 #print <($2) display the contents of file whose 1204 name is in variable $2 1205 1206 Further feature: 1207 1208 If < is specified, and you use an expression after it, you can also 1209 specify starting and ending line of the file that you want to use, 1210 in this way: 1211 1212 #print <(string-expr;[start];[end]) 1213 1214 Note: if you use a plain text as file name (like in #print <myfile ) 1215 you cannot specify starting and ending line. 1216 1217 If starting line is not specified, powwow begins from the first line, 1218 if ending line is not specified, powwow stops at the end of the file: 1219 1220 #print <("myfile";3;42) print lines from 3 to 42 of myfile 1221 1222 #print <("myfile";;57) print lines from start of file to 57 1223 1224 #print <("myfile";;) print whole file 1225 1226 Note that you can use expressions instead of filename, starting line 1227 and ending line: 1228 1229 #print <($5;4;3+@0) print file whose name is in variable $5 1230 from line 4 to line 3+@0 1231 1232 Of course, you can still use the whole file in the old way: 1233 #print <("myfile") or #print <myfile 1234 1235 1236 Further feature (another): 1237 1238 The starting and ending line can be specified ALSO when you use a ! 1239 before an expression: 1240 1241 #print !(string-expr;[start];[end]) 1242 1243 In this case, powwow executes the Bourne shell command contained in 1244 the string, and prints ONLY lines from <start> to <end> of its output. 1245 1246 Also here, you can use expressions instead of Bourne shell command, 1247 start and end, and powwow still begins from first line if <start> 1248 is not specified and/or stops at the end of the output if <end> 1249 is not specified. 1250 1251 Both these special features are supported ALSO in #send, #exe, 1252 #emulate and #var. 1253 ----------------------------------------------------------- 1254 Send text or result of an expression to MUD 1255 #send [< | !]{text | (expression)} 1256 1257 The simplest use of #send is to evaluate an expression and to send 1258 the result to the MUD. More generally, #send is very similar to #print, 1259 with the only difference that the final text is sent to the MUD rather 1260 than displayed on screen. 1261 The meaning of < and ! is the same, and #send does the expected things 1262 when they are used. 1263 1264 Example: 1265 1266 #send <mytext stuff a text into the mud 1267 #send !awk ' {print "tell arthur " $0} ' file 1268 say a file to your friend 1269 #send ("say I have been playing for " + %(timer/86400000) + " hours") 1270 timer is a variable holding the number of millisec 1271 elapsed since last timer reset, and the big number 1272 after it converts the elapsed time in hours. 1273 ----------------------------------------------------------- 1274 Execute text or result of an expression 1275 #exe [< | !]{text | (expression)} 1276 1277 Evaluate the expression and get result, 1278 then execute result as if typed from keyboard. 1279 If < or ! is specified, #exe behaves exactly like #print, 1280 but executes the final text as if typed. 1281 1282 Example: 1283 #exe ("sigh") is the same as typing sigh from keyboard. 1284 1285 #bind control_s=#exe ("#capture emergency" + %(@-7++)) 1286 (control_s must be a user defined key) 1287 safe capture to file: each time you press control_s, 1288 a different file is opened as capture. 1289 1290 #exe <mytext read the file mytext and execute all the 1291 commands in it, one line at time. 1292 Very useful to read a set of #alias for example 1293 ----------------------------------------------------------- 1294 Process a text/expression/file as if received from remote host 1295 #emulate [< | !]{text | expression} 1296 1297 Evaluate expression and get result, then process result as if received 1298 from remote host 1299 If < or ! is specified, #emulate behaves exactly like #print, 1300 but processes the final text as if received from remote host 1301 (check for matching #actions, extract prompt, etc.) 1302 1303 This command is particularly useful to test and debug #actions. 1304 Example: 1305 1306 #emulate The assassin is dead! R.I.P. 1307 #emulate <myfile 1308 ----------------------------------------------------------- 1309 Put a text or expression in a variable / delete a variable 1310 #var variable[=[[< | !]{text | (expression)}]] 1311 1312 Evaluate expression and get result, then put result 1313 in the specified variable. 1314 If < or ! is specified, #var behaves exactly like #print, 1315 but puts the final text into the specified variable. 1316 If you specify no right-hand expression, powwow puts the current value 1317 of the variable on input line, to allow you edit it. 1318 If you specify no right-hand expression, BUT YOU USE the =, powwow 1319 deletes the variable and frees memory used by it. 1320 1321 Note: If you use a numbered variable rather than a named one, 1322 instead of a number you can place an expression after the $ or @ 1323 and before the = 1324 Example: 1325 1326 #var @7=22 (same as #(@7=22) ) 1327 #var $-4 = hello (note that you do not need quotes 1328 since you are using a plain text) 1329 #var $-4 = ("hello") (if you use parenthesis, you must also 1330 use quotes) 1331 #var $test= long sentence (all the spaces but the first following 1332 the = are placed in the variable) 1333 #var $(2+4) = <myfile (put the whole file in $6. Remember 1334 that string variables cannot be longer 1335 than 1024 characters...) 1336 #alias calc=#var @-1 = !echo '$0' | bc -l 1337 (place result from bc calculator into @-1) 1338 1339 #var $target (put current value on input line) 1340 1341 #var $my_variable= (delete $my_variable and free memory) 1342 ----------------------------------------------------------- 1343 Write text to a file 1344 #write [> | !](expression ; file) 1345 1346 Evaluate expression and get result, then write result into file. 1347 By default, text is appended at the end of the file. 1348 1349 If > is specified, #write deletes the contents of the file before 1350 actually writing the text. 1351 1352 If ! is specified, #write assumes second parameter to be 1353 a Bourne shell command (instead of a file name) that is executed 1354 using the text as its input. 1355 1356 Example: 1357 1358 #write ($test; "myfile") (append contents of $test to myfile) 1359 1360 #write !("55+12";"bc -l") (execute 'bc -l' writing text to its 1361 standard input) 1362 1363 Advanced `#write' usage: 1364 1365 If you are using a terminal allowing multiple windows (an X11 graphic 1366 terminal for example) it is possible to duplicate/split powwow output 1367 to multiple windows using #write. This is more a UNIX topic rather 1368 than a powwow-specific one, but that's it. Here is a brief summary: 1369 1370 First, compile the `catrw' mini-program i.e. type 1371 $ make_it catrw 1372 if the above worked, type 1373 $ mkfifo fifo 1374 This will create a special file named `fifo' in the directory 1375 (any other name would do, of course) 1376 Then you have to open another window. This depends on the terminal 1377 you're using, but for X11 terminals the following works: 1378 $ xterm & 1379 On the second window, type 1380 $ exec catrw fifo 1381 (in case this gives you an error, try just `catrw fifo') 1382 Now return to the first window and start powwow normally. 1383 To send text to the second window from within powwow, type: 1384 #write ("some text"; "fifo") 1385 You should see `some text' (without the quotes) immediately 1386 appear in the second window. 1387 1388 Of course you may now want to send text automatically 1389 to the second window: just use #write ( <your-text> ; "fifo") 1390 from within an #alias, #action or whatever you like. 1391 1392 P.S.: 1393 for experienced users: if you are using the `bash' shell, 1394 you don't need `catrw' as you can use 1395 $ exec cat <> fifo 1396 instead of the above 1397 $ exec catrw fifo 1398 ----------------------------------------------------------- 1399 Set/show internal variables 1400 #setvar name[={number|(expr)}] 1401 1402 Evaluate the expression and get result, then set the internal 1403 variable `name' to that value. 1404 1405 Known internal variables are: 1406 1407 buffer with `buffer' different from zero, powwow saves 1408 the most recent text from the MUD in a circular list 1409 (which is `buffer' bytes long) and writes it 1410 at the beginning of #capture and #movie files when 1411 you open them. This is useful if something important 1412 happens suddenly and you want to log it somewhere: 1413 you can start #capture and/or #movie even _after_ the event 1414 has happened and it will still get written to the file. 1415 1416 if `buffer' is zero (default), powwow starts logging 1417 text from the MUD only at the moment you activate 1418 #capture or #movie. 1419 1420 To discard the text stored in memory by `buffer', 1421 change its value (for example, set it to zero 1422 and then back to a non-zero value). 1423 1424 lines the number of lines your terminal has. Powwow usually 1425 autodetects it correctly, but on few terminals you may 1426 have to set it manually. 1427 1428 mem the maximum length of a text or string, in bytes. 1429 The default is 0 (zero) which means no limit. 1430 I added it only to prevent bringing down the whole system 1431 with things like 1432 #while (1) #($foo += $foo + "x") 1433 Consider it an emergency setting, as powwow _discards_ text 1434 and strings longer than the limit. 1435 The failsafe limit set when loading a savefile from an older 1436 version is 1Megabyte, which won't give any problem 1437 (like increased memory usage) as powwow allocates memory 1438 only when it *has* to. 1439 1440 timer the number of milliseconds since program start. 1441 It can be changed to synchronize with an external clock 1442 like MUD ticks. 1443 1444 Example: 1445 1446 #setvar timer=0 (reset internal timer to 0) 1447 #setvar timer=20000 (make internal timer restart from 1448 20000 milliseconds) 1449 #setvar timer (show timer and let you edit it) 1450 1451 #setvar mem=1048576 (max strings length is now 1Megabyte) 1452 ----------------------------------------------------------- 1453 Send raw data to MUD 1454 #rawsend {text | (expression)} 1455 1456 This is mostly a MUD debugging tool, but it can be useful in some cases. 1457 Like its cousin #send, #rawsend evaluates the expression (or unescapes 1458 the text) and sends the result to the MUD. The difference is that 1459 #rawsend does NOT add a final newline, nor does IAC escaping to protect 1460 ASCII 255 characters. On the other hand, #rawsend can handle ASCII 0 1461 characters, while plain #send can't. 1462 ----------------------------------------------------------- 1463 Send raw data to screen 1464 #rawprint {text | (expression)} 1465 1466 Like its cousin #print, #rawprint evaluates the expression (or 1467 unescapes the text) and sends the result to the screen. The difference 1468 is that #rawprint does NOT add a final newline. On the other hand, 1469 #rawprint can handle ASCII 0 characters, while plain #print can't. 1470 ----------------------------------------------------------- 1471 1472INLINE CALCULATOR: 1473 1474 The inline calculator is used to evaluate expressions inside 1475 #(), #print (), #exe (), #send (), #if (), #while(), #for (), #do (), 1476 expressions in pattern of #actions and in other commands allowing () 1477 1478 The inline calculator recognizes the following objects: 1479 1480 numbers (only integers are supported) 1481 decimal numbers: 1482 simply write them. 1483 1484 hexadecimal numbers: 1485 use '#' as prefix: #F is 15, #a0 is 160, and so on. 1486 1487 numbers in any other base: 1488 use base# as prefix: 2#101 means 101 in base 2 (that gives 5) 1489 7#14 gives 11, etc... 1490 1491 if you use negative non-decimal numbers, you must put '-' 1492 before the base: - 2#101 is -5, 2#-101 causes an error. 1493 1494 it is possible to chain more than one '#': 1495 3#12#100 = (3#12)#100 = 5#100 = 25 1496 1497 both base and argument must be numbers, not variables: 1498 things like 7#@count or @count#7 are not allowed, you will 1499 have to use an #exe for that. 1500 1501 quoted-strings (i.e.: strings in " ") 1502 1503 NOTE: 1504 since version 0.6d, powwow performs unescaping on quoted strings 1505 when they are evaluated. For example "\"" is the string that contains 1506 the character " only. 1507 1508 timer (number of milliseconds since last timer reset) 1509 1510 map (string containing the last 999 steps you walked, 1511 as the #map command) 1512 1513 variables: 1514 @n with n within -50 and 9, are numeric-variables 1515 $n with n within -50 and 9, are string-variables 1516 1517 Since version 0.8, also named variables are supported: 1518 1519 @any_name1 1520 $any_name2 1521 1522 The name following @ or $ can contain any of these chars: 1523 uppercase or lowercase letters ('A'...'Z' and 'a'...'z') 1524 underscore ('_') 1525 numbers ('0'...'9') 1526 Anyway, the first char of the name must NOT be a number. 1527 1528 Remember that powwow is case sensitive: 1529 $test and $Test are NOT the same variable 1530 1531 Named variables are created the first time you use them 1532 and can be deleted only using the #var command 1533 1534 A special named variable is $prompt, which contains 1535 the current prompt. It cannot be deleted. 1536 Another special variable is $last_line, which contains 1537 the last non-empty line received from the MUD. Again, 1538 it cannot be deleted. 1539 1540 Difference between the various kind of variables: 1541 1542 Numbered variables with negative counter (@-50..@-1 and $-50..$-1) 1543 and named variables are global: 1544 They can be accessed at any time, but cannot be used for the 1545 substitution performed by #alias, #action, #while and #for. 1546 1547 Instead, numbered variables with positive counter (@0..@9 and 1548 $0..$9) are local: 1549 A new set is created (and initialized to zero) every time powwow 1550 executes an #alias, #action, #while or #for, and the old set 1551 is made invisible. After the #alias (or #action, #while, #for) 1552 is executed, the old set is restored. 1553 Note that also @0..@9 can be used for parameter substitution, 1554 and not only $0..$9. 1555 1556 Variable names as expressions: 1557 1558 The symbols $ and @ are implemented as normal operators, 1559 which means that variable names can be arbitrary expressions. 1560 For example, 1561 $(1-3) is the numbered variable $-2 1562 @("foo"+"bar") is the named variable @foobar 1563 $$1 is the variable whose name is in $1 1564 1565 operators between numbers: 1566 ++ -- + - 1567 * / % 1568 + - 1569 << >> 1570 < <= > >= == != 1571 & | ^ 1572 && || ^^ 1573 = *= /= %= += -= <<= >>= &= ^= |= &&= ^^= ||= 1574 , 1575 ( ) 1576 (% and %= always return non-negative values) 1577 (no help on these operators, see a C-language manual) 1578 (note: unlike C, operators &&, ^^ and || always eval both arguments) 1579 1580 random number generator: 1581 1582 rand positive-number (return a random number between 0 and n-1) 1583 1584 operators between strings: 1585 + chain two strings 1586 = assign a string to a string-variable 1587 += append a string to a string-variable 1588 - compare two strings: result -1 if s1<s2, +1 if s1>s2, 1589 0 if s1==s2 1590 < <= > >= == != compare two strings 1591 .? number of chars in a string 1592 :? number of words in a string 1593 ? position of first occurrence of second string in the first 1594 * convert first char of a string into its ASCII code or vice versa 1595 % convert string into its numeric value or vice versa 1596 1597 operators between a string and a number: 1598 (string is first argument) 1599 : n-th word of a string 1600 . n-th char of a string 1601 :< :> <: >: .< .> <. >. return part of a string, in this way: 1602 : before > or < means 'mark the n-th word from the left' 1603 . before > or < means 'mark the n-th char from the left' 1604 : after > or < means 'mark the n-th word from the right' 1605 . after > or < means 'mark the n-th char from the right' 1606 > means: return from marked word/char to end 1607 < means: return from start to marked word/char 1608 1609 so we get: 1610 :< n first n words 1611 :> n from the n-th word (include) to the end 1612 <: n from the begin to the n-th word (included) 1613 >: n last n words 1614 1615 and similarly for .< .> <. >. 1616 1617 * repeat a string n times: "ab" * 3 gives "ababab" 1618 *= usual shortcut: `$x *= n' is the same as `$x = $x * n' 1619 1620 functions for low-level color handling: 1621 1622 noattr (string containing the escape sequence to reset terminal 1623 colors and attributes -- bold, underline, inverse) 1624 1625 attr "quoted-string" 1626 (return the escape sequence needed to turn on 1627 the attributes and colors in the string. 1628 Syntax of the string is the same as #mark, #hilite, etc) 1629 1630 1631 Examples: 1632 1633 #print ($5="Hello, world") (assign "Hello, world" to $5 1634 and print it) 1635 #print ("This is a test">:3) (print from the 3rd word from the right 1636 till the end of the string) 1637 Result: "is a test" is printed on screen 1638 1639 #action >+exp ^You have scored $1 exp={#print;#print ("You gained " + 1640 ( $1 - @-5) + " exp. points since last score"); #(@-5 = $1)} 1641 1642 (when you type 'info' in MUME, one of the lines you get is: 1643 You have scored xxx exp. points ... 1644 The #action above intercepts this line, prints it, prints the 1645 difference between your current score and the contents of 1646 variable @-5, then copies your current score in @-5) 1647 1648 #print ($5 = (attr "bold green") + "Hello, world!" + noattr) 1649 1650 (same as first example, but with colors/attributes. 1651 Rememeber to print noattr at the end of every colored line, 1652 or everything appearing on the screen after your line 1653 will be colored as well) 1654 ----------------------------------------------------------- 1655 1656HOW INLINE CALCULATOR IS IMPLEMENTED 1657 1658 Info and hints to get the most out of calculator and/or hack it. 1659 1660 The structure `op_list[]' defined in xeval.c contains definitions for 1661 all the implemented operators, one for each line. Have a look at it 1662 to find things like: 1663 1664 precedence (first number in each line) 1665 associativity (LEFT or RIGHT) 1666 LEFT means that 1+2+3 actually is (1+2)+3 1667 RIGHT means that 1+2+3 actually is 1+(2+3) 1668 (replace numbers and operators with what you are actually using) 1669 if it is unary, i.e. needs ONE argument 1670 PRE_UNARY means that the operator comes before its argument, 1671 POST_UNARY is the opposite 1672 or binary i.e. needs TWO arguments 1673 1674 Note that stuff like `attr', `rand', `@' and `$' are actually 1675 implemented as PRE_UNARY operators (named variables are treated as an 1676 exception to this), thus `$(1+5)' and `attr ("bold"+" "+"inverse")' 1677 are fully allowed. Also note that using `$(5)' is a good way to avoid 1678 the parameter substitution performed by aliases, #action, #for, #while 1679 and use instead the actual variables. 1680 1681 `timer', `map', `noattr' are implemented as read-only values: 1682 the calculator simply substitutes them with their value 1683 1684 Remember that there is a , (comma) operator: 1685 Instead of `#(foo);#(bar)' you can use `#(foo, bar)' 1686 Using comma operator is easier for both you and powwow, since it uses 1687 a single command instead of two. 1688 ----------------------------------------------------------- 1689 1690ATTRIBUTES: COLORS AND OTHER HILIGHTINGS 1691 1692 Some commands use attributes to specify the visual appearance of text. 1693 The following attributes are available: 1694 bold, blink, underline, inverse 1695 -- the obvious effects 1696 reverse -- same as inverse 1697 [color] [on color] -- foreground and/or background 1698 Colors are: 1699 black, red, green, yellow, blue, magenta, cyan, white and 1700 BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, none 1701 ('none' means to use default and is implemented as a color) 1702 1703 Examples: The following are all valid attributes: 1704 none -- no attribute, use default 1705 green -- only foreground 1706 on white -- only background 1707 yellow on cyan -- foreground and background 1708 inverse bold -- 1709 blink red on blue -- you can use multiple attributes, 1710 but you must put 'bold' 'inverse' 1711 and/or 'underline' BEFORE colors 1712 1713 Observe that bold, blink, underline and reverse work with all terminals 1714 that support these attributes, but colors only on terminals that 1715 support ANSI color escape sequences. 1716 1717 Capitalized colors (BLACK..WHITE) are non-ANSI high intensity colors, 1718 and will not work on all terminals (They work on the 'aixterm' terminal 1719 emulator under AIX, but they may work on other terminals as well. 1720 Let me know if you find other terminals that support them). 1721 1722 Notes for IBM PC and compatibles with VGA or SVGA cards in text mode: 1723 -- yellow is actually brown 1724 -- bold is usually represented as high intensity 1725 -- blink can be represented either with actual blink or 1726 high intensity background - depends from card configuration 1727 (it is possible to reprogram it - I can send details if asked) 1728 ----------------------------------------------------------- 1729 1730HISTORY 1731 1732 Powwow keeps in memory the last 127 lines you typed from keyboard. 1733 If you want to recall one of them (to correct a mistake for example) 1734 you just need to press your arrow-up key or control-p to scroll through 1735 the whole history, one step at time (see COMMAND LINE EDITING below 1736 in the text for details about editing keys). 1737 1738 Another way to find a certain line in the history is to type the first 1739 few chars of it, and then press M-TAB to tell powwow to complete the 1740 line for you. If you hit M-TAB repeatedly, powwow will cycle 1741 through all the possible completions. 1742 1743 Also, you can use the '#put' command to add a line to history 1744 as if you typed it (see above for help on #put). 1745 ----------------------------------------------------------- 1746 1747WORD COMPLETION LIST 1748 1749 Powwow also remembers the last 512 words you typed from keyboard. 1750 This list of words is named `word completion list'. If you have already 1751 typed a long or difficult word, you can type the first few chars of it 1752 and then press TAB key to ask powwow to complete it for you. 1753 Again, if you hit TAB repeatedly powwow will cycle through 1754 all the possible completions. 1755 1756 Powwow can also complete the name of any built-in command even if 1757 not present in the word completion list. 1758 1759 Also, you can use the '#add' command to add a word to word completion 1760 list (see above for help on #add). 1761 ----------------------------------------------------------- 1762 1763COMMAND LINE EDITING 1764 1765 The default key bindings for line editing follow quite closely Emacs: 1766 These are all the keys, together with the reserved names that identify 1767 their function (they can be listed typing '#bind edit'): 1768 1769 Key: Function name: Description: 1770 1771 ^A &begin-of-line beginning of line 1772 ^E &end-of-line end of line 1773 ^B &prev-char backward one character 1774 ^F &next-char forward one character 1775 ^P &prev-line use previous line in history (step backward) 1776 ^N &next-line use next line in history (step forward) 1777 ^D &del-char-right delete character under cursor 1778 BS &del-char-left delete character left of cursor 1779 ^K &kill-to-eol kill to end of line 1780 ^T &transpose transpose previous character with next 1781 (if at the end of the line, the two last) 1782 ^L &redraw-line redraw your command line. 1783 This is useful if something garbles your input 1784 line. 1785 ^Q &clear-line clear input line. 1786 ^W &to-history put current line in history and clear input 1787 line. This is useful when you are typing a long 1788 line and need to send another urgent command 1789 first. 1790 ^Z &suspend suspend powwow in the background 1791 Tab &complete-word complete the word being typed to the last 1792 matching word in the history (or added with an 1793 #add command; see above). 1794 Hit multiple times to browse the possible 1795 completions. 1796 This is similar to the GNU Emacs M-/ command. 1797 M-Tab &complete-line complete the line being typed to the last 1798 matching line in the history. 1799 Hit multiple times to browse the possible 1800 completions. 1801 M-f &next-word forward one word 1802 M-k &redraw-line-noprompt 1803 redraw command line, discarding prompt 1804 M-b &prev-word backward one word 1805 M-d &del-word-right delete word right of cursor 1806 M-BS &del-word-left delete word left of cursor 1807 M-l &downcase-word turn word to lowercase 1808 M-t &transpose-words transpose previous word with next 1809 M-u &upcase-word turn word to uppercase 1810 Ret &enter-line the most obvious: execute the typed line 1811 LF &enter-line same thing, but for ^J key (some terminals 1812 send this when you hit return) 1813 (none) &insert-string insert on command line the specified chars 1814 1815 M-x means pressing the META or Alt key at the same time as x, 1816 or pressing and releasing the escape key, then typing x. The former 1817 way doesn't work on all terminals. 1818 1819 ^x means pressing the Control key at the same time as x. 1820 1821 If your terminal has arrow keys, they can be used to move the 1822 cursor and step around in history. In addition, you can define your 1823 own key bindings for sending quick commands (see the #bind command). 1824 If you have a vt100-compatible terminal, the numeric keypad is 1825 predefined for movement (keys 2, 3, 4, 5, 6, 7, 8 and 9). 1826 1827 Remember that ALL keys can be redefined... 1828 1829 1830 A brief note about &insert-string: 1831 1832 By default no key is bound to this function, and it works somewhat 1833 differently than other editing functions. 1834 1835 For example, say you don't have `{' and `}' on you keyboard 1836 (it happens on all italian keyboards -- like mine -- and other ones). 1837 Obviously, typing { or } gets quite difficult. A solution is: 1838 1839 #bind F11=&insert-string \173 1840 #bind F12=&insert-string \175 1841 1842 where \173 and \175 are typed normally: a backslash and three digits. 1843 Once you defined these two bindings, hitting F11 will be exactly like 1844 typing { and hitting F12 will be exactly like typing } . 1845 1846 Another possible use is to enter strange characters or strings: 1847 1848 #bind F10=&insert-string Ro\353ntgen 1849 does exactly what you expect: insert "Ro�ntgen" on the input line 1850 ( � is the ASCII char (octal)353 or (decimal)234 ) 1851 as if you typed it (of course you could also type the first few chars 1852 of the name then hit TAB if that name is already in the word completion 1853 list...). 1854 ----------------------------------------------------------- 1855 1856SECURITY 1857 1858 When you define an #action that automatically sends something back to 1859 the MUD you are connected to, you must be VERY careful since you may 1860 allow other players to force you to execute commands. 1861 Let's explain better: Suppose you define the following #action: 1862 1863 #action >+autogroup ^&1 starts following you.={#print;group $1} 1864 1865 Even though this may look harmless, such an action is potentially 1866 lethal, for the following reason: 1867 If you receive a text from the MUD containing something like 1868 1869 Cauldron ;remove all;drop all;kill dragon starts following you. 1870 (for example it may be an emote, many MUDs allow it) 1871 1872 powwow will realize that the line matches with the action you defined 1873 (remember that &n can match text of every length, even if containing 1874 spaces or ; ) and will execute this: 1875 1876 {#print;group Cauldron ;remove all;drop all;kill dragon} 1877 1878 The consequences of such a command can be easily imagined... 1879 There are two strategies to avoid such embarassing situations: 1880 1) Use #send and calculator. In fact this is NOT dangerous: 1881 1882 #action >+autogroup ^&1 starts following you.= 1883 {#print;#send ("group "+$(1))} 1884 1885 (in the worst case you will send some semicolon-separated commands 1886 to the MUD, but I saw no MUDs accepting multiple commands as clients 1887 do...): 1888 1889 2) Try to use $n instead of &n, so that semicolons and spaces 1890 are skipped. 1891 1892 #action >+autogroup ^$1 starts following you.= 1893 {#print;group $1} 1894 1895 WARNING: 1896 versions older than 0.7a were bugged and they did NOT skip 1897 semicolons (but they skipped spaces), so also using $n was 1898 dangerous! 1899 1900 If you really need to use a &n, check you are not losing security, 1901 and if you cannot write safe code, use calculator as in point 1). 1902 Note that this is NOT dangerous too: 1903 1904 #action >+autogroup ^&1 starts following you.=group $1 1905 1906 since if someone tries to force you as explained above 1907 it will not work, because #action allows only ONE command to follow 1908 the pattern and you did not place braces around "group $1", 1909 so only the first command (in this case "group <name>") 1910 will be executed. 1911 1912 In every case, remember the best strategy is: check what you are doing, 1913 and do not lose control. If you are not sure a command is safe, better 1914 not to use it. 1915 ----------------------------------------------------------- 1916 1917LIMITS 1918 1919 Powwow has the following limitations: 1920 1921 Numeric variables are defined as 'long', that means 32-bit integers 1922 on most systems. 1923 1924 String variables, text lines and commands by default have no length 1925 limits. If you want, you _can_ set a max limit with `#setvar mem'. 1926 Powwow discards text and strings longer than such a limit. 1927 1928 Exceptions: the labels/patterns of #aliases, #actions, #prompts, 1929 #marks, #in/#at etc. cannot be longer than 4095 chars. 1930 The same limit (4095 chars) applies for the input line. 1931 (the number can be changed by modifying the symbol BUFSIZE) 1932 1933 Unnamed ('numbered') variables must have indexes from -50 to 9. 1934 (the 50 can be changed modifying the symbol NUMVAR, the 9 cannot 1935 be increased due to hardcoded limits) 1936 1937 Inline calculator can hold up to 100 suspended operations, due to 1938 parentheses and/or inverted priority of operators. 1939 (the number can be changed by modifying the symbol MAX_STACK) 1940 1941 The depth of nested/recursive aliases, actions, prompts, #while and 1942 #for commands is limited to 100 nested calls. 1943 (the number can be changed by modifying the symbol MAX_STACK) 1944 1945 The number of loops of a #while or #for is limited to 10000. 1946 (the number can be changed by modifying the symbol MAX_LOOP) 1947 1948 Automap can be at most 999 steps. 1949 (the number can be changed by modifying the symbol MAX_MAPLEN) 1950 1951 History can contain at most 127 lines. 1952 (the number can be changed by modifying the symbol MAX_HIST) 1953 #history commands can execute other #history commands, up to 1954 MAX_HIST levels of recursion. 1955 1956 Word completion list can contain at most 512 words. 1957 (the number can be changed by modifying the symbol MAX_WORDS) 1958 1959 Up to 32 MUD (or spawned) connections can be open simultaneously. 1960 (the number can be changed by modifying the symbol MAX_FDSCAN) 1961 1962 For all other resources, the only limit is the available memory. 1963 ----------------------------------------------------------- 1964 1965THE BREAK KEY 1966 1967 It is usually Control-C or DEL (it depends from the terminal you use). 1968 1969 Powwow cannot redefine it, but you need to hit it twice in a row 1970 to actually stop powwow. 1971 This is because hitting it only once is used to stop command parsing: 1972 if you enter a long loop using internal commands 1973 (for example: #while (1) drop 1 coin) 1974 you can simply press your break key and powwow will immediatly exit 1975 from the loop with this message: `#interrupted. Press again to quit.' 1976 1977 If you press the break key again, you will exit powwow. 1978 Otherwise, if you first type something, then you press break key once 1979 more, you will get again: `#interrupted. Press again to quit.' 1980 ----------------------------------------------------------- 1981 1982ADVANCED TOPIC: SUBSTITUTIONS AND UNESCAPING 1983 1984 WARNING: 1985 this is a bit complicated and not recommended for beginners, 1986 as the explanation given at the beginning about $n and \'s might 1987 suffice in many cases. So you might skip this paragraph if you want. 1988 1989 Still reading? Ok, this is it: 1990 1991 We described in the beginning that adding \'s to $n delays text 1992 substitution in aliases and actions. Actually, every time powwow 1993 is asked to execute a command, it can make one or more of the 1994 following operations on the command itself before executing it: 1995 1996 Step (a) : `PARAMETER SUBSTITUTION' or simply `substitution' 1997 1998 (a1) place in $1..$9 the correct words 1999 2000 (a2) replace every occurrence of $1..$9 with the contents of the 2001 corresponding variable. Also replace every occurrence of @1..@9 2002 with the contents of the corresponding variable. 2003 Note that if one or more \ are preceding a $n or @n, 2004 it will be NOT substituted. 2005 2006 Step (b) : `JUST IN TIME SUBSTITUTION' or `jit' in short 2007 2008 (b1) replace every occurence of #{expression} with the value of the 2009 expression. Also replace every occurrence of ${name} and @{name} 2010 with the contents of the corresponding variable. Again, 2011 if one or more \ are preceding a #{expr}, ${name} or @{name}, 2012 it will NOT be substituted. This substitution works also 2013 for numbered variables ${number} and @{number}. 2014 2015 Step (c) : `UNESCAPING' 2016 2017 (c1) Remove ONE \ from every list of consecutive escapes, 2018 unless they are followed by one or more ` (i.e. reverse-escaped) 2019 For example, \\\$1 is replaced with \\$1 2020 2021 (c2) Remove ONE ` from every list of consecutive escapes immediately 2022 followed by a list of consecutive ` 2023 For example, @``` is not modified, 2024 while \\` is replaced with \\ 2025 and \\``` is replaced with \\`` 2026 2027 The steps actually executed vary from command to command, 2028 but are always ran in order: 2029 if both present, (a) always precedes (b) 2030 if both present, (a) always precedes (c) 2031 if both present, (b) always precedes (c). 2032 2033 ----------------------------------------------------------- 2034 2035 When each step is performed/not performed: 2036 2037 Step (a) (substitution) is performed when executing one of the 2038 following: 2039 aliases, actions, prompts, #for or #while 2040 2041 Step (b) (jit) is performed when executing _any_ command that allows 2042 a single instruction, and is executed on that instruction before 2043 running it. The list is: 2044 #alias, #action, #prompt, #at, #bind, #connect, #do, #for, #identify, 2045 #if-#else, #in, #init, #nice, #while. 2046 2047 Also performed on normal (not yet implemented for regexp) patterns 2048 of #actions before matching them. On regexp patterns, step (c) 2049 is made instead. 2050 2051 Step (c) (unescaping) is performed any time that step (a) 2052 and/or step (b) are performed. 2053 2054 In addition, unescaping is also performed on text 2055 (not on expressions) following all #commands that allow plain text: 2056 #add, #emulate, #exe, #mark, #print, #put, #send, #var 2057 2058 on labels of all #commands that allow labels: 2059 #alias, #action, #prompt, #at, #in 2060 2061 and last, on text that is not a #command nor an alias 2062 before sending it to the MUD, unless the last operation on the 2063 text was _already_ an unescaping. 2064 2065 Examples: 2066 2067 #alias fb=cast 'fireball' ${target} 2068 #var $target=troll 2069 fb (effect: cast 'fireball' troll) 2070 #var $target=dragon 2071 fb (effect: cast 'fireball' dragon) 2072 2073 #action >chase ^${target} leaves $1={#print; #alias f=$1} 2074 (whenever `dragon' leaves the room, 2075 the alias 'f' is set to follow it) 2076 2077 #action >chase2 ^\${target} leaves $1={#print; #alias f=$1} 2078 (the text `${target}' will be matched 2079 literally) 2080 WARNINGS: 2081 2082 Step (b) is NOT automatically performed on text typed from the keyboard 2083 so for example `#print ${target}' just prints literally `${target}' 2084 and not the contents of the variable. 2085 If you need step (b) on text you type, you can do something like: 2086 #alias /=$0 2087 and then prepend all commands with `/ ' : 2088 / #print ${target} 2089 2090 Step (b) is not yet implemented for regexp actions/prompt due to 2091 internal difficulties. As a workaround, step (c) (unescaping) 2092 is instead performed on regexp patterns. 2093 2094 Since powwow 1.1.3, unescaping is performed also on the text coming 2095 from substition and jit. This causes subtle incompatibilities with 2096 previous versions in case $n contains any \ or \` . 2097 I tried to avoid this incompatibility, but it is really complicated 2098 to do since I want the text coming from substitution to be subject 2099 to jit as well. So you (and me) will have to live with it :-( 2100 ----------------------------------------------------------- 2101 2102ADVANCED TOPIC: SPECIAL COMMAND #PROMPT 2103 2104 Automatic command execution triggered on prompts 2105 #prompt [[<|=|>|%][+|-]label] [{pattern | (expression)}=[command]] 2106 2107 WARNING: 2108 this is quite a complicated topic too. You will only need to read this 2109 paragraph if you want to mess with prompts in strange ways, as powwow 2110 usually handles prompts correctly. 2111 2112 Second warning: 2113 #prompt works only on the main MUD connection. 2114 2115 O.K, since you are still reading, let's get a bit technical about 2116 powwow internals: 2117 2118 (WARNING: this changed since powwow 1.1.7:) 2119 2120 Unless you use #actions, powwow sends immediately to the screen 2121 whatever text it receives from the MUD. It sends to screen both 2122 newline-ended lines (we'll name these `full lines') 2123 and lines not ended with a newline (`incomplete lines'). 2124 Now, there are two problems: 2125 1) there's no way to know whether an incomplete line is actually 2126 finished or there is a continuation we still have to receive. 2127 2) powwow cannot know if the line, or an initial part of it, 2128 is a prompt. 2129 2130 When powwow receives a line (either full or incomplete), 2131 its beginning part may be a prompt, so it matches #prompts on the line. 2132 If the beginning part is _actually_ a prompt, #prompt should 2133 execute #isprompt on it, to let powwow recognize the prompt as such. 2134 2135 To be exact #isprompt must also specify how long the initial prompt is, 2136 so that powwow can split it from the rest of the line. 2137 For this reason, #isprompt is invoked with a numerical argument: 2138 #isprompt <number> 2139 or 2140 #isprompt (expression) 2141 2142 a)If the number (or the result of the expression) is positive 2143 and equals to (n), #isprompt declares that the initial prompt 2144 is (n) characters long. 2145 b)If the number is negative and equals to (-n), #isprompt declares 2146 that the initial prompt is the same length as the parameter $n. 2147 c)If the number is 0 (or is missing), #isprompt declares 2148 the whole line as a prompt. 2149 2150 Also, if a #prompt does not run #isprompt, it is interpreted as 2151 'this text is not a prompt' 2152 2153 Putting #isprompt in a #prompt inhibits further attempts to match 2154 that part of the line against both #prompts and #actions 2155 (so should be used only on a complete prompt, not on a part of it) 2156 2157 NOTE: Since a prompt may be followed by other text, when using 2158 regexp patterns in #prompt it is important not to end the pattern 2159 with $ (which matches the 'end of line') 2160 2161 Examples: 2162 2163 On MUME the prompt starts with either `o' or `*' and finishes with `>' 2164 So the regexp pattern ^[o\*].*> will match all prompts and nothing else 2165 To do the same using normal patterns, one should use two patterns 2166 (and two #prompts): ^o&1> and ^*&1> 2167 2168 On other MUDs of course the possible prompts will vary, so one must 2169 find which pattern (or patterns) will match all the possible prompts. 2170 If it also matches strings that are not prompts, care is required 2171 _not_ to run #isprompt in such cases. 2172 2173 Let's continue with the MUME example: using regexp patterns, 2174 a correct #prompt is: 2175 2176 #prompt %default ^[o\\*][^>]*>= 2177 {#isprompt -1; #($prompt = "xyz " + attr "bold" + $prompt + noattr)} 2178 2179 Note that the pattern contains _two_ backslashes instead of one, 2180 as powwow unescapes regexp patterns. 2181 Also, [^>]*> is used instead of .*> to stop matching at the _first_ `>' 2182 (regexp by default would match the longest text possible, 2183 stopping at the _last_ `>' in the line) 2184 2185 The #prompt above correctly matches every MUME prompt, 2186 runs #isprompt -1 on it 2187 (which declares that the prompt is as long as $1 2188 since in regexp patterns $1 is the whole match, it is a good choice) 2189 then modifies the prompt in a custom way 2190 (puts it in bold then appends it to "xyz ") 2191 2192 Of course #prompts may do whatever one wants, but with a limitation: 2193 they must run #isprompt _before_ modifying the prompt, or unpredictable 2194 things could happen. 2195 2196 To have the same effect with normal patterns, the following 2197 would be needed: 2198 2199 #prompt >default1 ^o&1>= 2200 {#isprompt (2+.?$(1)); #($prompt = "xyz " + attr "bold" + $prompt + noattr)} 2201 2202 #prompt >default2 ^*&1>= 2203 {#isprompt (2+.?$(1)); #($prompt = "xyz " + attr "bold" + $prompt + noattr)} 2204 2205 The expression after #isprompt meanxs "2 plus the length of $1" 2206 which is obviously the correct length, as $1 does not contain 2207 `o' (or `*') and `>'. 2208 2209 Final note: 2210 If the prompt is longer than a whole line, it may be drawn incorrectly 2211 and may interfere with the input line (yep, it's a bug). 2212 2213 MUME players who happen to own a Valar+ character will find this 2214 useful too: 2215 #prompt >default3 ^+&1>={#isprompt (2+.?$(1))} 2216 or, to use regexp patterns: 2217 #prompt %default ^[o\\*\\+][^>]*>={#isprompt -1} 2218 2219 ----------------------------------------------------------- 2220