# Kira documentation

=====================================================================
Introduction
------------

Kira is one of many mudclients available for linux and windows. At
the moment, it is still quite in a development stage, although more
and more standard features are slowly being added. You will likely
find many shortcomings, especially in the graphical version as it
lacks some standard things most X programs have - like a menu, or
scrollbars. In the future however, many of the now lacking features
are scheduled to be fixed, so you might as well get used to the
program now!

Kira was designed with some ideas in mind: it's a free (open source)
client for a terminal environment (there is a graphical version for
windows and X, but most of the ideas are designed for use on a
terminal and later added in the graphical version), slightly portable
(well, I had only two systems to test it on and make versions for, but
with a little luck the code should not be too difficult to adapt to
other operating systems as well), and very personizable. You can
change practically anything, including basic keymappings. The
downside to this is that you _have_ to create most basic keymappings,
but the inputfiles given with the program will do most of this work
for you. :)

All bugreports and new good ideas are very welcome. For more
information on planned features, see the todo section of this file.

=====================================================================
-------------------

This manual contains most of the information in the kira help files,
but is often more verbose and gives more examples. It is intended both
as a document for learning the client (for those who do not like to go
into helpfiles and find out for themselves how everything works), and
as a useful reference guide, where things are just explained a bit
better than in the helpsystem.

In order, this manual contains the following sections:
1. Introduction: a description of the goals for kira, see above.
manual contains.
3. Versions: gives an overview of the "versions" of kira (graphical
windows version, terminal version for linux etc.)
4. Features: gives a brief overview of the things you can currently
do with kira.
5. Plans: and overview of development plans for kira
6. Compiling: some advices on how to compile kira from the code, for
those who have an operating system that the precompiled versions
don't work on, or who want to make a few changes in the code.
7. Getting started: some suggestions to get used to the client and get
it to do the first things you may want, as well as pointers to
the places where the most commonly used things can be found.
8. Overview: this is a section with the most important features in
kira, and a basic description on how to use them. This is mostly
useful as a lookup for concepts like "the window system", "input",
"getting help" etcetera. It may be a good idea to rifle through it,
just to know what is inside, but it would take quite a lot of work
to read all of it, and is probably not necessary for most users.
9. Settings: this will tell you about all the settings you can change
to customise your client. Again, you will not actually need most
of these, but just knowing that they exist could be useful.
10. Kirafunctions: an overview of the functions that kira defines by
default.
11. The parser: an explanation on how every input to kira gets parsed.
For most people, the first part will be enough. For those who
intend to do really difficult things, a second part is added with
an explanation that goes into the code, which could help you debug
very complex aliases.
12. Commands: this section gives a list of and help on all of the
commands.

=====================================================================
Versions
--------
Kira comes in 3 different flavours:

CursesKira: the most usual version. Linux based (although any system
supporting the curses library should work), works in a terminal and
doesn't need a graphical environment.
Uses the curses library for its IO.

XKira: the graphical version. Should be usable in any operating system
that supports the wxwidgets library.
Uses the wxwidgets library for its IO.

AnsiKira: the minimal version. This lacks some functionality like
automatic resizing of outputwindows and lines when the terminal
window is resized, but it should work in any system with a terminal
that supports ansi sequences.
The main idea of this version is to be able to get and compile a
mudclient anywhere you have a bit of discspace, without having to go
through difficult installations, compiling of libraries or anything
like that.
Does not use any non-usual libraries at all!

The 3 versions come with different makefiles, but use the same code
in most places.

=====================================================================
Features
--------

Currently, the following features are implemented:
- the ability to connect to a mud, send and receive text, and display
colours; that is, it does everything one usually does with telnet
- an intelligent inputwindow, that doesn't mangle your text with the
text received from the mud, and saves previous commands, even when
they were not executed / sent to the mud
- a separator: the ability to send/execute multiple commands at once
- a (slightly) intelligent parser, allowing you for example to send
some things unparsed (for example "hello \;)", although I wouldn't
recommend setting your separator to ";" for exactly this reason -
not until smiley protection is implemented, that is)
- the possibility (obligation, in fact) to do everything textbased
and the promise this will stay possible in every future release
- a split window for scrolling, allowing you to see new text while
viewing history
- keybindings, and an easy method to find keycodes
- aliases
- variables
- functions
- walkcommands
- timers
- logfiles, both plain text and html
- a printing command (trivial, but useful!)
- several settings, to change for example whether text is echoed (and
in what colour), information is displayed, or what strings to use
for kiraspecific things, like the separator, or the character to
give commands to the program
- some useful little extra's, like converse mode where every line
starts with the same command unless commanded otherwise
- a powerful windowsystem with multiple tabs, several lines and
windows per tab, which can be created and managed in a relatively
easy way
- the right not to think about any of the above and still have a
working client! In most cases, the commands needed to do something
will not be more complicated than is to be expected for the power
you need. This quite depends on your definitions of complicated and
powerful, so don't use this quote against me please :).

=====================================================================
Future plans
------------

The versions are planned as follows:
1: Basic mudclient, things most frequently used; a client that is
preferable over standard telnet clients.
2: A good tab/window system, control over the inputwindow by
commands, complete parsing syntax, working with files, functions,
logging.
3: Triggers and highlights. A #if-command. ifarg in aliases.
Typed variables. MCCP support. A serious windows (wxwidgets)
version.
4: Tabcompletion, scripts, ...
The things most good mudclients have, but no automapper, unless
somebody else wants to write that, since I consider that wasted
time, especially when you have scripts.
5 and beyond: MXP support, good graphical versions (clickability?
menus?), interesting features requested by others.

Naturally, this is all just planning ahead, so I'm giving no promises
whether all versions will really be as planned. Or whether all these
versions will ever appear. The current version is 2.2; since version
2, the window system has been changed a bit to enable the creation of
a reasonable widgets application, and the windows version now uses
more native window control.

As another note, since bugtesting takes a lot of work, maintaining the
code will be finished a lot earlier if you send us bugreports - then
we can get on with coding the fun and useful stuff. :)

=====================================================================
Compiling
---------
For the operating systems I can give instructions on how to compile,
there are binaries, so this section is probably only useful if you
are using hardware I don't have compiled versions for, or want to hack
into the code a bit and the fact the right version may not actually
compile immediately is confusing. :)

As a simple overview: most of the code is shared. The code that isn't
is easily recognisable by the names: iohandler_terminal, gui_widgets
etc.
The makefiles used for the different version define what files are
used in the compilation; these files are the same for any OS you can
run any given version on.
To include the right header files, the version.h file has to be
changed: it defines two things: a version (must be one of
VERSION_WIDGETS, VERSION_ANSI or VERSION_CURSES) and an operating
system (must be one of OS_WINDOWS or OS_LINUX). Setting these
values correctly, you should be able to use any of the versions on
any operating that supports it!

Ncurses version, linux.
- Make sure you have the ncurses library installed; in debian or
ubuntu this can be done by apt-get install libncurses5-dev, or
aptitude install libncurses5-dev. In other linuxes it's probably
something comparable.
CURSES_version.h to version.h and CURSES_Makefile to Makefile .
- Type 'make'. With a little luck, this should work. :)

Ansi version, linux.
ANSI_version.h to version.h and ANSI_Makefile to Makefile .
- Type 'make'. With a little luck, this should work. :)
- If you don't have inputfiles yet, or they don't work properly, use
./kira.exe assistant to go into a sort of wizard to define your
keys.

wxWidgets version, windows.
- Download a devpack for wxwidgets (the version I used can be found at
http://www.upcase.de/devpack.html )
WIN_version.h to version.h and open XKira.dev in dev c++.
- Press F9 to compile and run. With a little luck, this should create
a working version of kira and run it immediately.

For most systems, the version with the best chance of working would be
the ansi version, as that one uses as few libraries as possible.
This version will not work in windows, as windows does not support
ansi (or the net handler), but with a little luck may be compilable
on mac.
In a windows environment that does support ansi or curses (if that is
possible), use the same instructions as above, but change the
version.h file: use #define OS_WINDOWS instead of #define OS_LINUX.
To run the widgetsversion in a linux (or mac?) environment, you
should probably change the relevant version.h to have OS_LINUX

Note that if you have compiled a version yourself, most standard
functionality of the inputwindow still won't work - you need to have
the right inputfiles.
Some often good inputfiles can be found in the inputfiles/ folder;
pick the files for your version, and remove the version from their
name (for example, CURSES_kira.in cam be used as kira.in).
If the standard ones don't work and you have a terminal version
(anything other than the widgets version), you can create some
standard files using the kira assistant. To do this, start kira.exe
with argument "assistant".

=====================================================================
Getting started
---------------

Step 1:
If you have some version of microsoft windows:
manual, a helpfile help.in and some basic inputfiles. Unzip them
together in some folder, like C:/program files/kira. Make a
If you have some version of linux:
kira.exe, this manual, a helpfile help.in and a basic file
kira.in. Unzip these together in some folder, like ~/.kirafiles.
Then create a file containing the single line
"~/.kirafiles/kira.exe" (without quotes), call the file kira and
save it in your ~/bin directory. Typing kira anywhere should now
start the program.
If you have some version of linux and the precompiled versions
do not work:
Check the previous section on compiling. With a little luck, at
least the ansi version should work. This will give you a kira.exe
manual) and make an empty kira.in file. Place them all together
in some folder, like ~/.kirafiles, and continue as above.
Since your kira inputfile is empty, you will probably want to run
the kira assistant to get some default keybindings, or try
whether the standard ones supplied with the source work.
The assistant might take some time to work, but if you read
everything you  should be fine. You can run the assistant with
the command "kira assistant" rather than just "kira" to start the
program.
If you have some other operating system:
work if you have the right libraries - make sure version.h defines
only VERSION_WIDGETS and OS_LINUX (which hopefully makes the
experiment with the different defines.
If you get something to work, please mail me the result, and I'll
be glad to put it on the kira website as well. :)

Step 2:
or opening a terminal or xterm and typing kira. You can now log in
to a mud by using the connect command. For example, to log in to
the mud with adress discworld.atuin.net on port 4242, use:
#connect discworld.atuin.net 4242
Easy isn't it?
If you usually connect via telnet and don't know the gate, you can
skip it here as well:
#connect discworld.atuin.net
This will connect you on the standard telnet gate (23).
To send multiple commands (say A and B) at once, use
A;;B
To disconnect, use
#disconnect
If you feel the need to close the client, just type
#end

Step 3:
Play around a bit. Try out the possibilities of inputwindow: you
don't want to end up in a mud typing a long sentence and suddenly
having to run for your life and then finding out your configuration
or the program doesn't do quite what you expected it to. If you are
using the standard input files, or configured with the kira
assistant, there shouldn't be too many problems.

Step 4:
do exactly the things you can do with telnet, and have a nice
inputwindow. Kira also supplies keybindings, aliases, and much more
'#alias cow {#disp moo}', and then type 'cow'. If you haven't
changed the kirachar yet, this should give nice enough results :).
Check the commandlist for things you want to do, and experiment
with them a bit. :)

Step 5:
Unfortunately, all the things you did in the last step won't be
saved for next time you use kira... To do this, you need to edit
the inputfiles. Open kira.in and add a line like
"#load {c:\files\kira\basic.in}". Then you can open this file, and
want to display to yourself on opening the program here!
If you have multiple characters / play on several muds, I would
recommend putting only basic things in basic.in, like changing
settings, creating walkchars, and maybe something like
#bind 265 {#noecho key_F1} ;; #alias key_F1 ##
which might make working with the F1 key slightly easier (as you
don't have to remember the keycode anymore). You can also add
loads the file in which you save charspecific settings for your
first char.
Alternatively, in the linux version you can also add a file as a
commandline argument to kira. This file will be autoloaded.

Alternatively, rather than using aliases for different settings,
in the terminal variant you can give files as arguments. For
example, kira.exe discworld.in would start kira with the file
"discworld.in" in the directory you run the command from.
The kira.in file always gets loaded, if it exists.

- if you give a kiracommand (any command preceded by #, or
whatever you set the kirachar to), all words following it are
considered separate arguments. So, #alias cow say moo will make
an alias with name cow and value say, because only two arguments
are supported. To make longer arguments, use brackets:
#alias cow {say moo} does what you probably want.
- if you want some text sent literally (for example, you want the
text '######' sent to your mud), you can 'escape' it: if an
escapecharacter \ precedes any special character, this character
parsing.
- kira is, basically, not casesensitive. In commands and settings,
case does not matter. In your own aliases and variables though,
it does. So #end does the same as #END (quitting your program),
but if you create an alias cow, COW does not execute it.
- all existing commands and settings can be found in the
corresponding section of this manual. There you will also find
a nice explanation of what they do, and what they are used for.
The help on #alias, for example, will explain about using
aliases.

Have fun!

=====================================================================
Overview
--------

Here is an overview of the features of kira, and a description on how
to use them. Several of the subjects will have more detailed
information in their own chapters - in these cases there will be
pointers to those chapters.

+++ input

Input to kira can be made in two ways:
1. typing it in an inputwindow
2. placing it in a file that kira loads
More about files follows later. For the moment I assume you have
the client in front of you, and typing input straight into the
inputwindow. Commands loaded from a file are parsed completely the
same as when they would have been typed in.

Any text you write, save a few exceptions, gets send to the server
you are currently connected with (assuming you have a connection;
if you have no connection an errormessage will be given).
The first exception is any string that starts with the kirachar (in
default cases, this means the char #). A string like that is
interpreted as a command to kira. A complete overview of all legal
commands is given in the 'Commands' section of this file.
The second exception is parsing: every input gets parsed before
being executed / send. For a complete overview of what happens,
read the section on parsing. For most starting users, however, it
is probably enough to know that:
- two strings separated by the separator (by default this is ;;)
are executed as two different commands (a;;b first executes a,
then b)
- if you have defined aliases, and you use an alias, your text will
be replaced as described on the section about aliases (if you
have an alias 'speak' with value {say <1> <0>}, typing speak * +
will be interpreted as the command 'say + *').
- variables will be replaced by their value
- the \ char can be used to escape a special character that you
want to be interpreted as a normal character. So to send #### to

As a sidenote, when you type, the key is first tested as to whether
it's a macro key. If it is, only the macro will be executed. So if
you bind the 'a' key to some action, you can't type an 'a' anymore.

Also, note that every tab has its own inputwindow. So if you're
working with more than one tab, one tab doesn't have the same
'history' as the other.

+++ help

The helpsystem integrated in the program basically gives a browser
to read the file "help.txt", which contains information similar to
this file, but in a format suited for reading by the computer. You
can enter the helpsystem by typing
#help
or
#help
The help on a subject will give you information about it, and
describe if the subject is a command, the syntax you need to use
the command. You can also get the syntax of a given command by
typing: #syntax
The syntax is described in a formal way:
- the preceding kirachar is skipped
- keywords that have to be typed literally are capitalised
- words in  brackets have a default value
- two or more options, placed between [these] brackets and with
bars | in between, represent choices. You may only type one of
these.
- if several different syntaxes are given, all work, probably to
do something quite different. What they do should be described
in the rest of the help on the subject.

Some examples:

GOTAB <[tabnr | tabname | NEXT | PREV]>
valid inputs of this type are:
#gotab
#gotab next
#gotab prev
#gotab 0
#gotab tab_with_a_very_silly_long_name
BIND
BIND key value
valid inputs of this type are:
#bind
#bind 265
#bind 265 {shout help!}

+++ files

Any commands you give to kira, will be executed immediately, but
the effect will not be remembered for the next session. If you want
to make some more permanent changes, place your commands in a file.
To load a file, one can use the LOAD-command. So if you have a file
named basic.in, give the command
This will then execute all commands in the file basic.in. They will
not be echoed and no feedbackmessages will be printed, regardless
of your settings. Errormessages, however, will not be suppressed.

The program will always load the file kira.in, if it exists. Other
files can be given as command line arguments (terminal version
only at the moment). This can be quite useful if you play several
muds, or different characters, for example; you could make aliases
achaea that calls kira with achaea.in, and discworld that calls
kira with argument discworld.in.

For most cases, however, kira.in will be quite enough. Please
realise that if you ever want to use the kira assistant (which
isn't possible in the windows version yet, so you don't have to
worry about it if you use that), it's not a good idea to edit
kira.in too much: the assistant won't accept kira.in if it
doesn't have the following format:

#set kirachar
...

Of course, if the character chosen on the first line isn't #, the
character preceding 'load' should be this alternative character.
The file may contain empty lines, and comment, but nothing else.
The line with the kirachar may be skipped.
Please note that kira _will_ work if you change this file. Making
changes to the format only affects the assistant.

It is a very good idea never to change the kirachar anywhere else
than at the start of this file. As an example of what could go
wrong otherwise, imagine you first load the file bindings.in,
declaring for example
#bind 263 #key_backpace
and then you choose to set the kirachar to /:
#set kirachar /
when you press the backspace key, the command '#key_backspace' will
be executed, which doesn't mean anything to kira, and will
therefore simply be sent to the mud.

The kira assistant also recognises some files as generated ones,
and if you change those, the assistant - if you ever run it later -
may give a warning that she can't save those changes for you.
The assistant only uses files starting with kira_ (like kira_keys.in
or kira_numpad.in, but in future versions other such files may be
added), so you should be safe with anything else :).

As a sidenote: kira uses files where some other clients use
classes: if you want some specific behaviour (like certain aliases
put the basic commands you want to use everywhere in a first file
(loaded from kira.in), and the specific commands in other files.
Then you could, for example, do something like this:

+++ mudthings

There are a few features most slightly serious mudclients have.
These are:
- aliases
- functions
- keybindings
- variables
- walkcommands
- timers
- triggers
- highlights

Unfortunately, I haven't given triggers (and highlights, which is
really just a form of trigger) much priority yet, so I suppose I'm
not allowed to call kira a very serious client. They are planned to
be implemented in a future version though :)

Now, how to use what is implemented... I shall give a few examples
in this section. If you want a bit more power, I recommend reading
the sections on each of the subjects, and the section about the
parser as well.

Aliases:
--------
An alias is a system to create an alternative command. For example,
if your mud allows you to cast light on an object, you may find it
a good idea to create an alias 'light' that, when invoked, sends
'cast light on me' to the mud.
You can create an alias by using the ALIAS-command. To make the
alias described above, use the following command:
> #alias light {cast light on me}
then, when you type:
> light
kira will send the command 'cast light on me' to the mud.

you want to know more about that, I don't feel like doing a lot of
copy/paste work ;). Basically, use <:> to denote "all arguments",
and  to denote the n'th argument. Note that arguments are counted
from 0!

If you have the setting 'expandaliases' set to true, your alias
will be shown as the command it expands to. So when typing 'light',
the text 'cast light on me' will be echoed in your outputwindow.
If expandaliases is set to false (default), the alias will just be
echoed as the text you entered. While this is often a lot less
spammy, it is wise to set the option to true if you want to test
aliases.
If you want to know more about the available settings, read the

Be careful with nesting aliases. If, for example, you have an alias
alias1 calling alias2, and alias2 calls alias1, the program will try
to execute them for 100 steps, and then give an errormessage.
If you want to send a command that you also have an alias for, use
escape characters.
Example:
#alias alias1 alias2
#alias alias2 {\_alias1 hello!}
When calling alias1, the text 'alias1 hello' will be send to the
parser.

Keybindings:
------------
A keybinding is used to send a command to the mud when pressing a
single key. This is done regardless of the text currently in the
inputwindow, so you can type, for example, a long tell to someone,
and press the F12 key halfway to make you flee from combat, and
still continue to type. You probably can imagine some other uses
for this :).
The syntax to make a keybinding is very simple:
> #bind keycode value
Where # should be replaced with your kiracharacter, keycode with
the keycode of the key you want to bind, and value with a command.
Remember to put the command (and in some cases the keycode) in
{brackets}!

To find out the keycode of a given key, use the keycheck command.

So, if you want, for example, to have pressing Alt+k execute the
command "kill all", use:
> #keycheck
press alt+k
press k to check it's not the same keycode in your version, as that
would cause a lot of annoyance ;)
If it's the same, think of another key(-combination) for this
command. If it isn't, remember the code you found for alt+k (for
the example I'll assume the code is '27 107') and press escape. You
should now leave keychecking mode (it may take a few moments).
> #bind {27 107} {kill all}
Now pressing alt+k should have you execute the command "kill all".
Have fun!

Variables:
----------
A variable is used to (temporarily) remember a value. Since
triggers and calculation are not yet implemented, this find its use
mostly in aliases.
A variable has a name and a value. You can create / change a
variable using the var-command. To expand a variable, precede it by
$(or whatever character you have set variableChar to). Here are a few examples to make things more clear. Create a variable named myvar, with value "hello world". > #var myvar {hello world!} Expand the variable in a command. > #disp {$myvar}

The following is a slightly more useful combination of variables
and aliases.
> #alias trg {#var target {<0=\$target> <1:>}} > #alias kk {trg <:>;;kill <0=\$target> <1:>}
To see what this does:
> #set expandaliases true
> kk hublandish barbarian
> kk

Functions:
----------
Functions are a cross between aliases and variables. When a function
is called, the corresponding command is called with the given
parameters, and then the value of the corresponding variable is
pasted.

To make a function, just use the FUNCTION command. This works
similar to ALIAS. However, the function should set the value of the
variable with the same name, because when the function is called,
the value of this variable will be used as a result.
You can call a function by preceding its name with $(or whatever character you have set variableChar to). Here are a few examples to make things more clear. > #var counter {} > #function counter {#var counter \$counterI}
> #disp {$counter()} > #disp {$counter()}
> #disp {$counter()} > #disp {Counting...$counter() $counter()$counter()}

> #function first {#disp {Arguments are: <:>};;#var first <0>}
> #disp {$first(a,b,c)} As an extra, there are also some functions defined by kira. These can be called in the same way, but have dynamic value and can not be overwritten. A full list can be found in the kirafunctions section. Walkcommands: ------------- A walkcommand is used for quickwalking. This way you can make one-line-aliases to walk through the whole mud, for example. You can also use it to quickly walk through given directions. To use walkcommands, you first have to bind each command you want to use in a quickwalk to a char. > #walkchar n north ;; #walkchar e east ;; #walkchar s south > #walkchar w west ;; #walkchar r northeast ;; #walkchar u up After having done so once, you can use the walk-command to quickwalk. > #walk 2s5ere2rn2w ;; read sign;; #walk us ;; join Note that numbers are used to execute a certain walkchar several times. Timers: ------- A timer is used to run a command at set intervals. This could, for example, be used to display a clock on your screen, or to remind you to pray, or whatever you want, really! A timer is bound to a tab, and run there. This doesn't matter if you just stick to one (which most people will probably do), but for example if you are playing on two muds at the same time, your timer sending the pray command will only do this at the mud it was set for, not the one you're currently playing! Here are a few examples to make things more clear. > #timer clock 60 {$#noecho{#line print 0 {[KIRAhour():KIRAminute()]}$}} > #timer once 300 {#beep;;#del timer once} +++ the window system Unlike you might expect of a textbased client, kira has a reasonably advanced tab/window system. The basic principle is fairly easy: - A tab is your workspace. It's what you see when you start the program: everything. A tab typically contains a prompt (inputwindow) where you can type commands into, a textarea (outputwindow) where the text you typed and the text received from the mud goes into, a line to separate the inputwindow from the outputwindow, and a connection to some mud (or an empty connection if you're not connected yet/anymore). The description given above is a default configuration; you can add lines and windows. There can, however, only be one connection per tab. If you want more than one connection, create an extra tab. This will give you a complete extra workspace. The tab will have a prompt of its own, which you can use to make a connection in this workspace (for example), and to send commands over the connection. There can only ever be one tab visible. You can swap between tabs using the GOTAB-command. This will be explained below. - A window is basically a textarea. It's the thing where text from the mud and warnings are printed into, and where your commands are echoed (in the default configuration). You can choose to have more than one window at the same tab, although with the lack of triggers in this version that's probably not very useful yet. You can also choose to copy the window to another tab: the window will then be on both tabs, and either textarea will be updated when the other is. For examples of this, see below. - The prompt (inputwindow) is your way to give input to kira. The prompt is represented by a small textfield on the tab where the text you have typed is echoed. You can manipulate the inputwindow with some keycommands. For example, you can bind the backspace key to the command #key_backspace. Or you can make an alias to do something and then set the text in the inputwindow to 'run', so you just have to press return to run. - A line is just something to separate the windows (and inputwindow) on a tab and make the whole thing look a bit better. You can also use it to write specific (nonscrolling) information on, like 'TAB 1'. In the default configuration there's just the horizontal blue line between inputwindow and outputwindow, but you can make lines of any colour, and in any form, as long as it's rectangular. Every kind of window mentioned above can be placed anywhere on your tabs; even out of sight. The upper left corner of your screen is considered (0,0). You can use any location in the form A%+B, which for x-location means A% of the total number of columns of the screen, rounded down, plus B columns extra. As such, the lower right corner of the screen is at (100%-1, 100%-1). These locations must be given without spaces between %, + and the numbers. The possibilities are best explained by giving examples. For complete information, take a look at the description for the commands 'TAB', 'WINDOW', 'INPUT', 'LINE', 'TABOVERVIEW' and 'SEND'. It is best to try all of the following, using kira with default configuration. First, as an utterly useless example of the possibilities, create a layout with 3 windows, separated by lines: The main window (tab 0, upper left (0,5), lower right (right of the screen, 2 places below the bottom of the screen). > #window add main_win 0 5 100% 100%-7 Delete the old main window (couldn't be done before, because there must always be at least one window). > #window del 0 The other two windows: > #window add echo_win 0 0 50% 4 > #window add info_win 50%+1 0 50%-1 4 And some lines to separate the lot: > #line add {} 0 4 50% 1 blue > #line add {} 50%+1 4 50%-1 1 blue > #line add {} 50% 0 1 4 blue Oops, that looks silly. Let's correct this mistake. > #line Check that the line we just added has number 3. > #line del 3 > #line add {} 50% 0 1 5 blue And now tell the tab how we want to use each of the windows. > #tab set main main_win > #tab set echo echo_win > #tab set info info_win Now the upper left window will be used to echo your commands, the upper right window will be used to give information and warnings, and the main window (the big one) will be used to display text from the server. Of course, since such a configuration is quite ugly and very useless, I don't expect anyone to use it. This was just an example of the possibilities. A slightly more useful example is the following, that will demonstrate the use of multiple tabs for multiple muds. I assume the default configuration again, to get it back either restart kira, or type: > #window add win0 > #window del main_win > #window del echo_win > #window del info_win > #line del 1 ;; #line del 1 ;; #line del 1 The default configuration has one tab. Add another one for the second mud. > #tab add > #keycheck Press F1 or ctrl+1 or esc+1 or whatever key/combination you want to use for going to your first tab. If it gives a result, go on to press F2, ctrl+2 or whatever you want to use for going to your second tab. When you have that, press ctrl+tab or whatever you want to use for going to 'the next tab' (where 'next' is considered circular). Remember all results. Then press escape. In the following, replace "27 49" by the result of the first key(-combination), "27 50" by the result of the second one, and "27 9" by your alternative for ctrl+tab. > #bind {27 49} {#noecho{#gotab 0}} > #bind {27 50} {#noecho{#gotab 1}} > #bind {27 9} {#noecho{#gotab next}} Now you can go to whichever tab you like by pressing the right combination, and the command to do so won't even be echoed! From now on, I will assume you can work with this. So if I say 'go to tab 0' (tab 0 being the first tab), I mean you should either press ctrl+1 or whatever key(-combination) you set the first command to, press ctrl+tab if you are in tab 1 (the second tab), do nothing if you are in tab 0, or type something like #gotab 0. Now make space to display the main window of the other tab. First, go to tab 0. > #window resize win0 {} 100%-7 > #window move win0 0 5 > #line add separatorline 0 4 100% 1 And copy that window to this tab! > #window copy win1 0 0 0 100% 4 Now do the same for the other tab. The commands for this can be executed from either of the tabs, so let us, to make a point, simply do it from the first one :) > #window resize win1 {} 100%-7 1 > #window move win1 0 5 1 > #line add separatorline 0 4 100% 1 white black normal \ 1 > #window copy win0 1 0 0 100% 4 Now go to tab 0 and enter: > #connect discworld.atuin.net 4242 Then go to tab 1 and enter: > #connect nanvaent.org Now you can play both muds (although you're only really seeing one at the same time), and if something important happens on one mud while you're busy with the other, you'll still see the 4 most important lines. This may actually be useful sometimes :). As a nice extra, try: > #alias mud0 {#send 0 {<:>}} > #alias mud1 {#send 1 {<:>}} Now you don't have to change to the other tab to execute commands on it, you can just precede it with the right alias! A last useful feature is following. > #taboverview This will give you a nice overview of all your tabs, windows, lines and inputwindows. If you're only interested in one of those, you can type #tab, #window, #line or #input (without arguments) to see any of them. If you're interested in the possibilities, I would recommend you to at least read the documentation on TAB, WINDOW, LINE and INPUT. ===================================================================== Settings -------- To personalise kira, you will probably want to change some of the global settings at some point. You can view and change these settings using the command SET. To see the list of settings you can change (and their current values), use: > #set To see the current value of a specific setting, like keepinput, use: > #set keepinput To change the value of a setting, for example setting EOLspaces to 4, use: > #set EOLspaces 4 Settings are not casesensitive. For the stringsettings, their value is casesensitive; at the moment this only applies to the separator. So if you set your separator to aaa, AAA will not work. Most settings must be changed with care: old aliases and keybindings may cease to work; this can be very annoying since 'backspace', for example, is a keybinding. The reason for not working, of course, is that your old aliases, binds, walkcommands and everything will not be changed if you decide to change something like the kirachar or separator. It is usually best to change these settings directly in kira.in, the file that always gets read, before doing everything else, and then not to change them anymore. Naturally, this is not necessary for the other settings: the ones that determine, for example, colours and how the inputwindow works. Here is an overview of all kira's settings, and what they are used for. +++ echoexpanded +++ Default: true Description: if true, kira will print commands separated by the separator on different lines. If false, a group of commands will be echoed completely; in this case, kiracommands will not be echoed differently from mudcommands, and the entire group will be echoed with colours and attributes determined by mudcommandcolours, and not be echoed if echoMudCommands is set to false. Limitations: argument must be either true or false. +++ echokiracommands +++ Default: true Description: if true, kira will print the kiracommands you give (any command preceded by #, or whatever is your kirachar) to the outputwindow in the attributes determined by the setting kiracommandcolours. If false, no kiracommands will be printed. Limitations: argument must be either true or false. +++ echomudcommands +++ Default: true Description: if true, kira will print the mudcommands you give (any command not preceded by #, or whatever is your kirachar) to the outputwindow in the attributes determined by the setting mudcommandcolours. If false, no mudcommands will be printed. Limitations: argument must be either true or false. +++ eolspaces +++ Default: 50 Description: if a line is too long to fit in the outputwindow, it will be split over several lines. Kira tries to split between two words, but won't do it if that would create more than spaces at the end of a line. Limitations: argument must be numeric. Apart from that, if eolspaces is too big (causes less than 2 characters per line), it will be ignored: 2 characters per line is the minimum. Note: the main reason to supply this setting is because you may want to play with very small windows. For the rest, there is no real reason to change it, as it doesn't start being relevant unless the window gets to work with really large words. +++ escapecharacter +++ Default: \ Description: the character whose working is described in the parsing section, needed to prevent characters from being parsed. Limitations: must be a single character. +++ expandaliases +++ Default: false Description: if true, kira will show expanded aliases: on using an alias, what you typed will be gagged, but the commands that get created by expanding the aliases will be echoed. If false, what you typed will be echoed instead. Limitations: argument must be either true or false. +++ indent +++ Default: 2 Description: if a line is too long to fit in the outputwindow, it will be split over several lines. All lines except the first one will tbe preceded by spaces. Limitations: argument must be numeric. +++ keepinput +++ Default: true Description: if true, on pressing the returnkey the input will stay in the inputwindow, selected to overwrite immediately. If false, the inputwindow will be empty for the next command. Limitations: argument must be either true or false. +++ kirachar +++ Default: # Description: the character all kiracommands must start with. Limitations: must be a single character Warning: if you change this, some keybindings/aliases/whatever you made before will not work anymore. Most importantly (?), your inputwindow might cease to work nicely, since the backspace, for example, is a keybinding too. So if you want to change this setting, do it first thing. +++ kiracommandcolours +++ Default: {b_black, yellow, a_bold} Description: the attributes to display kiracommands. The commands will only get displayed if the setting echokiracommands is set to true. Limitations: the argument to this command must have a form as in the default: both backgroundcolour, foregroundcolour and attribute must be set. If not given, those are reset to the defaults. The order in which they are given does not matter. Comma's are not necessary. Possibilities for the argument: Foregroundcolours backgroundcolours attributes -------------------------------------------------- black b_black a_normal red b_red a_standout green b_green a_bold yellow b_yellow a_italic blue b_blue a_underline magenta b_magenta a_reverse cyan b_cyan a_blink white b_white a_dim default (white) b_default (b_black) a_invisible a_strikethrough Please note that yellow is not real yellow. It's more brown. Only with attributes bold or standout does yellow become real yellow. Since attributes only affect the foreground, you cannot have a yellow background. +++ literalbrackets +++ Default: [ Description: everything within these brackets (if preceded by the escapecharacter) will be taken literally. 'within these brackets' $like this$: correct nesting is taken into account. See the section about parsing for more information. Limitations: you only have to give the openbracket; the closebracket must match in the following way: [ matches ], { matches }, < matches >, ( matches ). Be very careful changing brackets, as you usually overwrite some other bracket, and things might not work properly anymore. +++ mudcommandcolours +++ Default: {b_black, yellow, a_bold} Description: the attributes to display commands to be sent to the mud. The commands will only get displayed if the setting echomudcommands is set to true. Limitations: the argument to this command must have a form as in the default: both backgroundcolour, foregroundcolour and attribute must be set. If not given, those are reset to the defaults. The order in which they are given does not matter. Comma's are not necessary. Possibilities for the argument: Foregroundcolours backgroundcolours attributes -------------------------------------------------- black b_black a_normal red b_red a_standout green b_green a_bold yellow b_yellow a_italic blue b_blue a_underline magenta b_magenta a_reverse cyan b_cyan a_blink white b_white a_dim default (white) b_default (b_black) a_invisible a_strikethrough Please note that yellow is not real yellow. It's more brown. Only with attributes bold or standout does yellow become real yellow. Since attributes only affect the foreground, you cannot have a yellow background. +++ parameterbrackets +++ Default: < Description: between these brackets (no nesting), numbers of parameters should be given in the definition of aliases and functions. See the information on the command ALIAS or FUNCTION for more information. Limitations: you only have to give the openbracket; the closebracket must match in the following way: [ matches ], { matches }, < matches >, ( matches ), and any other character matches only itself. Be very careful changing brackets, as you usually overwrite some other bracket, and things might not work very well anymore. +++ parsingallowed +++ Default: true Description: if parsingallowed is set to false, kira will not parse any input given from the inputwindow. Thus, everything you type will be sent to the mud unaltered. Only commands SET and END (#set and #end) will be interpreted and executed as normal. Indirect input, like texts you load from a file or commands generated by keybindings, will still be parsed. Warning: in noparsing mode, you will not be able to use aliases, variables and such (except those called by keybindings). +++ selecthistory +++ Default: false Description: if true, on browsing the inputwindowhistory (pressing the up/down-key, or whichever key hou have bound to the command #key_historyup / #key_historydown), the command in the inputwindow will be selected, enabling it to be overwritten immediately. If false, it will not be selected, with the advantage that text can be added to it immediately. Limitations: argument must be either true or false. +++ separatorincomment +++ Default: true Description: if true, kira allows you to use the separatorcharacter in comments. So > ## statement 1 ;; statement 2 is viewed as comment entirely. If *separatorincomment* is set to false, the above statement is seen as first a comment, followed by the command "statement 2". +++ separator +++ Default: ;; Description: The charactersequence that you need to put several commands in one line. Needed for example in aliases. Limitations: the separatorstring may not be more than 10 characters long. Warning: a command is cut up in single commands before it is executed. This implies that something like: #set separator @@ @@ do_something_else @@ do_another_thing will not work; in this case you need: #set separator @@ ;; do_something_else ;; do_another_thing However, after the first command, @@ is the separatorchar, so if you use ;; inside the second character in some way, this will NOT work anymore. Another warning: if you want to change this, it's best to change it before doing anything else, apart from other settings. This because some aliases/keybindings/whatever may not work anymore after changing this. If, for example, you had an alias created by #alias al {a;;b} and then set the separator to @@, on typing al a;;b will be send to the mud, instead of first a and then b. +++ showinformation +++ Default: true Description: if true, kira will display notifications like 'Okay. File loaded.' to let you know that what you wanted has been done the way you wanted it. If false, kira will not display any notifications, only warnings. There is no way to turn off warnings, except changing the sourcecode. Limitations: argument must be either true or false. +++ simpleparsing +++ Default: true Description: if true, the parser will give an error on constructions that do weird things with escaping character(group)s. Because most of the time these constructions are due to a mistake, it is generally best to keep this setting on. For more information on what it does, read the section about advanced parsing (and don't turn it off without having read this!). +++ variablechar +++ Default:$
Description: if this char is followed by the name of a function and
some arguments (possibly none) in round brackets (), the function
is executed with those parameter and, afterwards, the value of the
If this char is followed by the name of a variable, it is parsed
to the value of this variable.
Limitations: argument must be a single character.

=====================================================================
Kirafunctions
-------------

Similar to userfunctions (as explained in the section about functions
in the overview), kira supplies a few functions for your convenience.
These can be called by preceding the name with the variablechar ($by default) and giving arguments in brackets following the name (if no arguments are needed, just place brackets with nothing in it). For example: > #disp {$KIRAampm()}
> #disp {$KIRAdatetime(long)} At the moment, kira has the following standard functions: +++ KIRAactivetab +++ Arguments: none Description: this returns the number of the tab that is currently active (you are looking at it). +++ KIRAampm +++ Arguments: none Description: this will return whether it's am or pm, depending on the time set on your computer +++ KIRAcurrenttab +++ Arguments: none Description: this returns the number of the tab from which the current command is being executed. +++ KIRAdatetime +++ Arguments: give argument short for a brief version - anything else or no argument will give the long version Description: this returns the current date and time. If no argument is given, this is in the format "03-02-2007 12:48", if the argument is "short", it will be 070203_1248 instead (which may, for example, be quite useful if you want to keep a logfile for every mudsession). +++ KIRAdayofmonth +++ Arguments: none Description: this returns a number representing the day of the month. +++ KIRAdayofweek +++ Arguments: either number, desc or brief. If no arguments are given, brief is assumed. Description: this returns the day of the week. It takes (at most) one argument. If argument "number" is given, this will give the daynumber, from 0 (sunday) to 6 (saturday). If argument "desc" is given, a description is given ("Sunday", "Saturday", etcetera). If argument "brief" or no argument is given, this will give the first 3 letters of the day description ("Sun", "Sat" etcetera). +++ KIRAhour +++ Arguments: either ampm, or full. If no arguments are given, full is assumed. Description: this returns the hour of the day. If argument "ampm" is given, hours will be taken modulo 12. Otherwise, the full hour will be used. This is most useful in combination with KIRAampm and KIRAminute. +++ KIRAminute +++ Arguments: none Description: this returns a number representing the minute-part of the current time. It is mostly useful in combination with KIRAhour. +++ KIRAmonth +++ Arguments: either number or desc. If no arguments are given, desc is assumed. Description: this returns the current month. If argument "number" is given, month will be shown as a number (02 for februari), otherwise the (capitalised) name will be used. +++ KIRAwhitespace +++ Arguments: none Description: this returns a whitespace character. This is not the same as a space character, and some muds may treat it differently. +++ KIRAyear +++ Arguments: 1, 2, 3 or 4. If no arguments are given, 4 is assumed. Description: this returns the current year. If an argument N is given, only the last N digits will be shown. So$KIRAyear(2) will
return 07 or something similar.

=====================================================================
The parser
----------

+++ Basic explanation

Every command given to kira gets parsed on creation. If a line
contains several commands (separated by ;; or whatever you have set
the setting 'separator' to), the first of these is both parsed and
executed before the rest are considered. This secures that, for
example, a line like "#var target {bearded man};;kill $target" first creates a variable target for bearded man, and then makes you attack this target. The parser is easy enough to understand, but there are a few basic rules you should keep in mind: 1. EVERY command given to kira gets parsed on creation. This means every text you type will be send to the parser as soon as you press return, but also includes every text in a file you load, and (!!) commands sent to kira by an alias or keybinding you may have. Therefore, if you have a variable named 'text' with value 'It's not fair!', using > #alias whinge {say$text}
will be parsed to: "#alias whinge {say It's not fair!}" before
being executed. Therefore doing this will create an alias with
name 'whinge' that makes you say "It's not fair!" whenever you
use it. Changing the value of the variable text won't change the
result of the alias.

2. A special character in parsing is \ (or whatever character you
set as your escapecharacter). Usually, this character is
interpreted as "don't do anything special with the next
character" (exceptions will be explained later). Basically, this
means the next character will not be parsed.
So to continue with the above example, using
> #alias whinge {say \$text} will be parsed to "#alias whinge {say$text}" before being
executed. This will create an alias whinge with value
"say $text". If you then use > whinge the command "say$text" will be parsed and executed.
As a result, the line "say It's not fair!" will be send to your
mud.
To demonstrate the difference with the original approach, try
the following in kira:
> #var text {It's not fair!}
> #alias whinge1 {#disp {$text}} > #alias whinge2 {#disp {\$text}}
> whinge1
> whinge2
> #var text {Meanies!}
> whinge1
> whinge2
Seen the difference? :)

If the parsing character is the last character in a line, kira
ignores it. It won't be send to the mud. If you want to have a
slash displayed, use \\.

3. The following characters and strings have a special meaning for
the parser:
\  (escapechar)
Used mainly to tell the parser to not parse the next
character, and label the next character to be taken literally.
For example typing \#alias will send the text #alias to the
mud, instead of trying to execute the command #alias.
\ can be combined with _, = and square brackets [] as
explained in the next section. This is not often necessary,
unless you are going to do complex things.
$(variablechar) When the variablechar precedes the name of a function, followed by round brackets (), optionally with arguments in between, the function will first be executed, and the result will be pasted into the text. For example: > #var date {$KIRAdatetime()}
will create a variable containing the current date and time.
When the variablechar precedes the name of a variable, the
parser pastes the value of the variable instead. The longest
matching variable gets priority.
As an example, assume you have made two variables:
> #var var1 {hello world!}
> #var var11 {farewell cruel world!}
The parser will replace any (not escaped) occurence of $var11 by the text "farewell cruel world!". If$var1 occurs outside a
$var11, it will be replaced by the text "hello world!". If something like$hello occurs, while no variable hello
exists, it will not be replaced! Therefore it's relatively
safe to use dollarsigns for money or in mudaliases without
~  (specialchar)
The specialchar is used to create special characters. At the
moment, 3 options are supported:
~n creates a linefeed (ascii code 10)
~r creates a carriage return (ascii code 13)
~e creates an escapecode (ascii code 27)
;; (separator)
When the separator is encountered in a text, the text before
and after it will be parsed and executed as separate commands.
Each of the 4 abovegiven characters/strings can be replaced by
another character/string.

4. The characters _, =, [ and ] by themselves have no special
meaning and can be used without a problem. Just don't precede
them with the escapecharacter :).

Then what is the point? Well, each has a special goal.

Imagine, for example, you want to create an alias pray such that
when executed the command 'pray to Pishe' will be send to the
mud.
How would one do this? You cannot just make an alias
> #alias pray {pray to pishe}
as this would cause a recursive call: when typing pray, the
command 'pray to pishe' will be executed, which is itself an
alias, causing the client to go into a loop and eventually break
out with an error.
Having realised this, most would consider:
> #alias pray {\pray to pishe}
however, this won't work either. What will happen when you
enter this command is this:
- the parser only labels the second 'p'
- the executor creates an alias with name pray, and value
'pray to pishe'. The label given by the parser is only used
this run, and therefore not saved.
So if you then press pray, it will still execute 'pray to
pishe', which is an alias, which results in recursive calling,
and so on.
The correct alternative is:
> #alias pray {\\pray to pishe}
because when you type this, the following will happen:
- the parser replaces \\ by un unparsable \
- the executor gets to execute: #alias pray {\pray to pishe}
If you now type pray:
- the command "\pray to pishe" is send to the parser
- the parser labels the p as something to be taken literally
- the executor notices 'pray' is not to be read as an alias, and
sends 'pray to pishe' to the mud.

For most people, this will be enough to solve most problems. But
if you want to do a bit more than the average person, this is
where the special charactercombinations come in:

\_ means the same as \\\, \__ means \\\\\\\. Combining \ with 5
underscores means the character after the combination will be
labeled and not parsed at depth 6. Even better, if you make a
mistake, your text will not contain an overflow of slashes, so
> #disp {\\\hello}
looks a bit worse then
> #disp {\_hello}

\= is basically the same, except that the character directly
following \= will be taken literally at every depth

$[[...$]] means that ... must be taken literally 3 deep. It
is therefore the same as \__.\___.\___. You can imagine why I

If you intend to use these combinations, and know a bit about
programming, I would recommend reading the complete explanation
aliases. Or maybe even to not write bugs in the first place. :)

5. If you do strange things with the parser, an errormessage will
be given if the setting 'simpleparsing' is set to true (which it
is by default). If you want the full power of the parser, set
simpleparsing to false, and read the next section. If you want
to understand how the parser works you can read the next
information as well. However, if the above is enough for you,
just skip the next section :) It will probably just be
confusing...

+++ Complete explanation

I added this section for those who want to make quite complex
aliases / variables / whatever, and find themselves in the need to
debug those. It will explain exactly what happens during the parsing
and executing of a command. I assume you have read and hope you have
understood the easy explanation. You have? Good. Now you may forget
it again.

A command given to kira from the inputwindow, file or, for example,
an alias, goes through 4 different phases before being executed
completely: creating a "Command" type, cutting it up in parts,
parsing and then executing it. We will go through all of these now.

---
CREATING: every commandline given to kira from the inputwindow or a
file is immediately parsed into a "Command". Commandlines entered
from an alias or from another command are parsed into a Command as
well, but skip the first 2 steps.
1. Every character gets label '0'. Characters with label 0 will
also be known as 'unlabeled'.
A label will either be between 0 and 100, or 'infinity'. If any
of the steps in parsing lead to a label higher than 100, it will
be set to 100.
A label is interpreted as 'the depth to take this character
literally'.

2. If the command ends with a \, it gets removed. If it ends with
\_ or \=, it is removed and a warning is given.

3. Bracketnesting is checked: the labeled-string-parser goes
through the string, left to right.
If we come across a not-escaped closing bracket (when we aren't
looking for it) of any kind, an errormessage is produced and the
command is set to empty (this is not the same as a string of
length 0: that is just the 0-length command).
If we come across a not-escaped opening bracket, we find the
matching bracket. If there is none, an errormessage is given and
the command is set to empty. If there is, we continue checking
after this bracket.

There is some non-triviality involved in finding the matching
bracket: here, we must pay attention to nesting.
- If the openingbracket we found is a normal curly bracket ({),
we walk through the text following it, searching for an
unescaped closing bracket }. If we come across a closing
bracket for a literalsequence (\], \]] and so on), an
errormessage (incorrect nesting) is given and the command is
set to empty. If we come across ANY opening bracket, we find
the corresponding closing bracket (in the same way as
described here) and continue after that. If we find a closing
bracket }, we are done.
- If the openingbracket we found opens a literalsequence ($, \[[ and so on), we also walk through the text following it in search for an unescaped matching closing bracket ($, \]] or
whatever we were looking for). However, in this situation we
ignore any curly brackets we come across. So if we come across
{ or }, this is the same as meeting an A (or whatever). If we
come across a closing bracket for a literalsequence that does
not match our openingbracket (has a different number of square
brackets), an errormessage is given and the command is set to
empty. If we come across any literalsequence open bracket, we
find the corresponding closing bracket (in the same way as
described here) and continue after that. If we find the
matching closing bracket, we are done.

Here are some examples that hopefully make the above clear:
- { $} is not valid (\[ unmatched) - { \[ }$ is not valid       ({ unmatched)
- ${$ is valid             (comparable to $A$)
- ${$ } is not valid       (} unmatched)
- ] is not valid          (\]] unmatched)
- $[ \[$] is not valid      ($unmatched) - \[ { \[ }$ \] is valid     (comparable to $A \[ B$ \])
- { ${$ } } is not valid   (comparable to { $A$ } })
Summarizing, brackets should be nested in an intuitively correct
way, except that curly brackets inside literal brackets are
ignored.

4. All not-escaped occurences of the separator outside any brackets
are replaced by a special separatorcharacter. Spaces following or
preceding a seperatorcharacter are deleted.
So a command
> text 1;;text 2;;\text 3 {te;;xt 4}\;;text5
is parsed into:
> text 1text 2\text 3 {te;;xt 4}\;;text5
with all characters having label 0.

Note that in
> #noecho{a;;b}
the separator is inside the brackets, and therefore not (yet)
interpreted as a separator.

---
CUTTING: we now have a Command type, with separators neatly marked.
This Command is sent to the active tab, for cutting and executing.
The active tab will then execute the Command as follows:
1. If the string is empty, stop.
2. If the string does not contain a separatorcharacter, take the
whole string, and send it to the parser. This returns a
SingleCommand type. Set the string to empty. Go to step 4.
3. If the string does contain a separatorcharacter, take the part
before the separator and send it to the parser. This returns a
SingleCommand type. Remove this part (and the separatorcharacter
following it) from the string.
4. Execute the SingleCommand.

So a Command
"text 1text2\text 3 {te;;xt 4}\;;text5" with
all characters having label 0 is executed as follows:
- string = "text 1text 2\text 3 {te;;xt 4}\;;text5"
- parse and execute Command("text 1"),
string = "text2\text 3 {te;;xt 4}\;;text5"
- parse and execute Command("text 2"),
string = "\text 3 {te;;xt 4}\;;text5"
- parse and execute Command("\text 3 {te;;xt 4}\;;text5"),
string =
- stop

---
PARSING: as seen above, the parser will always get a single Command
(without separators) to turn into a SingleCommand. Here are the
steps the parser takes:
1. Find the first unlabeled(!) occurence of \. If there is none,
go to step 2. If there is, there are several possibilities:
a) The next character is [ (unlabeled). Count the number of
unlabeled square brackets following our slash. Determine the
matching closing bracket (we already checked in the CREATING
phase that there is such a bracket).
Delete those bracket combinations. Add the counted number of
brackets to the labels of everything that used to be between
them.
If simpleparsing is set to true and any of the characters
between the brackets was labeled, an error occurs.
As an example, the text ab$[cd$e
5600000007
is parsed to: abcde.
56227
Continue with step 1.
b) The next character is = (unlabeled). Delete the \=
combination and label the character following it with
'infinity'. If the character was labeled before and
simpleParsing is set to true, an error occurs.
As an example, the text a\=b
3000
is parsed to: ab.
3I
Continue with step 1.
d) The next character is either _ (unlabeled) or something
else. Count the number of unlabeled underscores following the
slash, and add one to that for the slash. We then delete the
\___-combination, and add the counter number to the label of
the character following it. If simpleparsing is set to true,
and the character was labeled, an error occurs.
As an example, the text a\__b
10000
is parsed to: ab.
13
If singleparsing is set to false, \__
003
is parsed to _
5
because a labeled underscore (or square bracket or any other
character) is treated as any labeled character.
Continue with step 1.

In the above, note that with singleParsing set to true only
unlabeled characters may be newly labeled. This seems quite
reasonable, since there are hardly situations where increasing
labels would be necessary, and when going wrong it could lead
to some quite hideous bugs.

2) Find and replace all unlabeled special charactercombinations
(like ~n, which is replaced by a newline character).
Other occurences of ~ (the specialchar) will not be parsed.

3) Walk through the string. Every time $(the variablechar) occurs unlabeled, and is followed by the name of a function and round brackets (), the function is executed, using the parameters given in the brackets. The function is then replaced by the value of the variable (if the variable is unset, it is simply removed). Walking through the string (looking for functioncalls) is then continued _after_ the inserted value. Anything inside the newly inserted value is therefore not parsed as a function again (in this step). 4) For all variables, in decreasing length: check whether the variable (variablename preceded by$, the variablechar) occurs
unlabeled in the text. If so, replace all occurences of the
variable with its value, temporarily adding an extra label to
the value. This is used for situations where a variable contains
another variable or itself. After having replaced all variables,
the temporary labels are removed.

5) If you haven't been in this step for 100 times yet, and any
variable or function was replaced in the previous two steps,
continue with step 1 (of the parsing section). Otherwise, go to
step 6. This is to secure that the value of variables and
functions does get parsed again, without ending up in an infinite
loop. To see how this works, you can try the following:
> #var santo {ho \$santa} >$santa
Also note that occurences of $that don't precede a variablename will be safely ignored. As a sidenote, the reparsing of the command after a variable has been encountered does NOT cause the re-evaluation of separators. 5) Parsing is now complete! The resulting SingleCommand is sent back to the tab. --- EXECUTING: as suggested above, the resulting SingleCommand is executed by the active tab. Note that if part of a command changes the active tab, the rest of the command will be executed by that tab. So > #tab add ;; #disp {Hello world!} will display "Hello world!" on the new tab. To execute a SingleCommand, the tab will do the following things: 1) The first check is whether the command is a kiracommand or an alias, and the first word is completely unlabeled. If not, this is a normal mudcommand, all labels are removed and the command is sent to the mud as a normal string. 2) If the first word of the command is the name of an alias: a) The rest of the labeled string will be split up in arguments; for each of these arguments the labels are decreased by 1 and the arguments are sent to the alias. b) The arguments will be inserted at the right places in the value of the alias, which is a labeled string as well. If the current depth < 100, a new Command will be created, cut up, parsed and executed from the resulting labeled string. Since this string is already labeled, the creating phase is started at step 3: checking the bracketnesting. 3) If the first word of the string is unlabeled, a kiracommand and not an alias (it is possible to be both, but in that case the command will be parsed as an alias), then the command will be executed depending on what it is. The arguments will be used either with all labels decreased by 1, or as a normal string. --- And that's all! To maybe lighten a few things up (or make them even more confusing), here are some examples: > #var var3 {\__$var}
As a first step, this is turned into a Command, where all letters
are labeled with 0; this is succesful as the brackets are nested
correctly.
There is nothing much to cut up, so the parser gets the entire
command, and changes it into
#var var3 {$var} instead. 0000000000030000 The executing functionality of the tab will then create a variable with name "var3" (this is a normal string) and value$var.
2000

In the following, I assume we already have a variable greeting with
value HI.
05
> #alias hello {say \$greeting} ;; hello - The program notes that brackets are nested correctly and creates a Comand #alias hello {say \$greeting}  hello
000000000000000000000000000000                    000000
which is sent to the active tab.
- The active tab cuts it up in two, and sends first
Command(#alias hello {say \$greeting}) 00000000000000000000000000000 to the parser, which acts as follows: * the first (and only) unlabeled slash is parsed away: #alias hello {say$greeting}
0000000000000000001000000000
* there are no more unlabeled slashes; there are also no
specialchars to replace; there is also no unlabeled occurence of
any variable, so the parsing of this Command is finished
- The active tab executes the resulting SingleCommand:
* the handler for creating an alias is called with arguments
"hello" (unlabeled string) and say $greeting (labeled). 0000000000000 * this creates an alias named "hello" with value "say$greeting"
(which is a labeled string (not yet a Command), but all labels
are 0).
- The active tab now sends the Command(hello) to the parser.
00000
- There isn't actually anything to parse, so this will simply
create a SingleCommand(hello).
00000
- The active tab will then execute this command:
* it is an alias, without arguments. Therefore
Command(say $greeting} 0000000000000 will be sent to the active tab for cutting, parsing and executing. * There is little to parse, so this Command is sent on to the parser unaltered. * The parser replaces$greeting by HI and doesn't do anything
000000000    05
else, so the tab gets to execute SingleCommand(say HI).
000005
* The tab recognises this as a mudcommand, and sends "say HI" to
the mud.

Some less worked out examples:

> #var var {hello world!}
> #var var3 {\__$var} >$var3
> #var var2 {$var3} >$var2
> #var var1 {$var2} >$var1

> #set expandaliases true
> #alias alias {$[<:>$]: <:>}
> alias a b c

> #var bing {bong!}
> #bind 33 {\$bing} > #var bing {beep} ===================================================================== Commands -------- Kira recognises the following commands: ALIAS BIND COLOUR CONNECT CONVERSE DEL DISCONNECT DISP DOECHO END FUNCTION GOTAB HELP INPUT KEYCHECK KEY_BACKSPACE KEY_DELETE KEY_END KEY_HISTORYDOWN KEY_HISTORYUP KEY_HOME KEY_IGNORE KEY_LEFTARROW KEY_RETURN KEY_RIGHTARROW KEY_SCROLLDOWN KEY_SCROLLSTART KEY_SCROLLSTOP KEY_SCROLLTOGGLE KEY_SCROLLUP KEY_SIMULATE KEY_TOGGLESELECT KEY_TYPE KEY_WORDLEFT KEY_WORDRIGHT LINE LOAD LOG NOECHO PASTE RESET SEND SET SYNTAX TAB TABOVERVIEW TIMER UPDATE VAR WALK WALKCHAR WINDOW In the following sections, each command will be treated seperately, and its use will be explained. In all explanations, defaultvalues are assumed for settings like brackets, the separator and special characters. ------------- +++ ALIAS +++ ------------- Syntax: ALIAS ALIAS text ALIAS aliasname command Explanation: ALIAS without arguments or followed by ALL (case sensitive) shows a list of all aliases currently in memory. ALIAS followed by a single text shows a list of all aliases in memory that start with the given text. ALIAS followed by a name and a command (warning: this command should be given as one argument, so most likely you will need brackets), creates an alias with name *aliasname*, that when invoked calls the command specified by *value*, inserting parameters in the specified places. To insert a finite number of parameters in the alias, there are 3 ways: argument n arguments n-m, separated by spaces. argument n, or w if argument n is not given Parametercount starts at 0, and thus ends at the number of arguments minus one, which we shall call 'last' from now on. The first syntax may be read as: . If, in the second syntax, n > m or n > last, then this argumentcode is ignored. If m > last, then take m := last. Also, in the second syntax, both n and m may be left out. n is defaulted 0, m is defaulted last. In the third syntax, there is no problem with w containing spaces. If you want to test aliases, setting expandaliases to true would be useful to see what everything does. > #set expandaliases true Examples: > #alias trg {#var target <0>} > #alias kk {kill <0=\$target>;; trg <0=\$target>} > kk man --> kill man --> #var target man > trg woman --> #var trg woman > kk --> kill woman --> #var target woman > #alias stupid {say <:>, <2:8>, <:1>,<3=hello>; <5=tweet tweet>} > stupid a b c d e --> say a b c d e, c d e, a b,d; tweet tweet ------------ +++ BIND +++ ------------ Syntax: BIND BIND keycode value Explanation: BIND without arguments shows a list of all keybindings in memory, together with their value. BIND followed by a single keycode shows the value the given key is bound to. BIND followed by a keycode and a value will create a keybinding on key (keycode), which will issue a command (value) when the corresponding key is pressed. Note that value will be send to the parser before being executed! A keycode may be anything, but a keycode representing a key is recommended (KEYCHECK can be used to find the code for a key). It is not a good idea to bind a key you may want to type, because that won't be possible anymore. Also, binding return or the kirachar is forbidden. Binding escape is possible, but it might not be a good idea considering forward compatibility; in a future version you may want to bind it otherwise. Examples: > #bind {150 4} {run;;run;;run} > #keycheck (press escape to leave keychecking mode, anything else to find its keycode; press F1 to find out its keycode - in the following I will assume 265) > #bind 265 {slash \$target with rapier}
> #var target {grizzly bear}

--> slash grizzly with rapier
> #var target yeti

--> slash yeti with rapier

--------------
+++ COLOUR +++
--------------

Syntax:
COLOUR
COLOUR DEFAULT back front
COLOUR WINDOW back front
COLOUR INPUT back front
COLOUR LINE back front

Explanation:
With this command, you can change kira's default colours. The most basic of
this is COLOUR DEFAULT: if the other 3 colour settings have not changed, this
defines the standard colours kira uses: you can use this to work, for
example, on a white screen with black letters (if no colour is given), rather
than the standard black screen with white letters. Note however that this is
likely not what you want - backgroundcolours are the non-bright version of a
colour (unlike you might expect from a white background).

Using COLOUR WINDOW, you can change the standard colour outputwindows are
given. Individual windows can be changed with the WINDOW command itself.
If back is set to "default", the backgroundcolour set with COLOUR DEFAULT is
used instead. If front is set to default, the default frontcolour is used.

Using COLOUR INPUT, you can change the standard colour for inputwindows.
There is no way to change individual inputwindows.
Again, if back or front is set to "default", the settings set with COLOUR
DEFAULT apply.

COLOUR LINE defines the standard colour lines are given, if their values for
back- and foregroundcolour are set to default.
If back is set to "default", the *foreground* colour set with COLOUR DEFAULT
is used instead. If front is set to default, the default background colour is
used.

COLOUR without any arguments shows the current colour settings.

Examples:
> #colour
> #colour default white black
> #line add {} 0 0 100% 1
> #colour default black white
> #colour line blue white
> #colour window green black
> #window resize 0 50% 50%

---------------
+++ CONNECT +++
---------------

Syntax:
CONNECT host

Explanation:
Use connect to create a connection with the given host on the given
port (port is defaulted 23, the standard telnet gate).
The host may either be a hostname or an ip-adress. The port must be
numeric. Only one connection can be made per tab.
Use DISCONNECT to drop the current connection.

Example:
> #connect discworld.atuin.net 4242
> #disconnect

----------------
+++ CONVERSE +++
----------------

Syntax:
CONVERSE text
CONVERSE STOP

Explanation:
This command allows you to set a text before any command you enter
in the given tab (if no tab is given, this will default to the
current tab). Only normal commands will be preceded by this text,
kiracommands are excluded.
To stop convert mode, just use CONVERSE STOP.

CONVERSE can be used for easily pasting large amounts of text to
someone, or to precede all text in a tab by an alias, for example.

Examples:
> #converse {tell friend}
> Hello my friend!
> How are you today?
> #converse stop

> #alias starttext {smile <:> benevolently}
> #converse starttext 1
> #gotab 1
> friend1
> friend2
> #disp {test}
> #converse stop

-----------
+++ DEL +++
-----------

Syntax:
DEL [ALIAS | BIND | FUNCTION | VAR | WALKCHAR] description
DEL TIMER description

Explanation:
Del allows you to delete any given alias, keybinding, function,
variable, walkchar or timer.
Use RESET to delete all of these at once.

Since timers are bound to a tab, you can indicate from what tab the
timer should be deleted. If no tab is given, the current tab is
assumed.

Examples:
> #alias hello {#disp {hello world!}}
> #del alias hello
> hello

> #alias #unalias {#del alias <0>}
> #unalias #unalias

------------------
+++ DISCONNECT +++
------------------

Syntax:
DISCONNECT

Explanation:
Disconnect the current connection. This might be needed if things
go wrong, and you want to reconnect. Usually it is not necessary;
most (if not all) muds have a quit-command, that will disconnect
you and is preferable.

------------
+++ DISP +++
------------

Syntax:
DISP text

Explanation:
Displays the given text in the outputwindow given by window. If the
argument window is omitted, the text will be displayed in the main
outputwindow in the current tab.
Ansi sequences are supported, so you can display the text in any
colour you like. Any supported ansi sequence is of the form
[m, which you can enter as ~e[m (assuming default
settings, so ~ is the *specialcharacter*).

About the codes: the easiest way, when you want something displayed
in attribute a, frontcolour b, backcolour c, is using the ansi
sequence ~e[a;b;cm. The sequences are as follows:

Attributes       Foregroundcolours    Backgroundcolours
-------------------------------------------------------
none **      0     black    30          black    40
bright       1     red      31          red      41
italic       3     green    32          green    42
underscore   4     yellow   33          yellow   43
blink        5     blue     34          blue     44
dim          6     magenta  35          magenta  45
reverse      7     cyan     36          cyan     46
hidden       8     white    37          white    47
striketrough 9     default  39          default  49

** resets attributes and colours to default

Please note that most attributes are not supported by kira (yet).
Most attributes are displayed as bright/bold.
Also note that it might be a good idea to end a line with \e[0m, if
you changed colours that line and haven't resetted them already.

Example:
> #disp {Hello. Welcome to the kira psychiatrist, $name.} > #disp {Please tell me more about your obsession with \e[31mred\e$0m} -------------- +++ DOECHO +++ -------------- Syntax: DOECHO command Notes: This command will never be echoed. Explanation: This command forces text to be echoed if echoable (all 'real' text is echoable, and commands if not stated otherwise). Even if this command is placed within a #noecho. Basically, this commands sets the settings echoKiraCommands, echoMudCommands and showInformation to true while executing the command. As a consequence, changing the settings echoKiraCommands, echoMudCommands and showInformation will only have a short effect, as those settings are reset after the command. Examples: > #set echomudcommands false > not echoed > #doecho {echoed!} > #noecho{#doecho{#echoed!}} > #set echomudcommands true > #doecho {#set echomudcommands false ;; test test} ;; retest ----------- +++ END +++ ----------- Syntax: END Explanation: Ends the program. None of your settings will be remembered for the next time you open kira (except the ones you have saved in files). ---------------- +++ FUNCTION +++ ---------------- Syntax: FUNCTION FUNCTION [USER | KIRA] FUNCTION text FUNCTION name value Explanation: FUNCTION without arguments or followed by ALL (case sensitive!) shows a list of all functions currently in memory (including all kira functions). FUNCTION followed only by USER (case sensitive!) shows a list of all non-kira functions currently in memory. FUNCTION followed only by KIRA (case sensitive!) shows a list of all kirafunctions currently in memory. FUNCTION followed by a single text (other than USER or KIRA) shows a list of all functions in memory that start with the given text, and shows their values for userfunctions. This is, again, case sensitive. FUNCTION followed by a name and a command (warning: this command should be given as one argument, so most likely you will need brackets), will create a function with name *name* that, when invoked, calls the command specified by *value*, inserting the parameters with wich it was invoked in the specified places. If the function already exists, it is overwritten. After invoking, the value of the corresponding variable will be used as the result of the function. So a function by the name of myFun will have to set the variable myFun to give a result (use the VAR command for this). To insert parameters into the function, the same methods as for aliases are used. There are 3 ways: argument n arguments n-m, separated by spaces. argument n, or w if argument n is not given Parametercount starts at 0, and thus ends at the number of arguments minus one, which we shall call 'last' from now on. The first syntax may be read as: . If, in the second syntax, n > m or n > last, then this argumentcode is ignored. If m > last, then take m := last. Also, in the second syntax, both n and m may be left out. n is defaulted 0, m is defaulted last. In the third syntax, there is no problem with w containing spaces. Apart from the functions you have created yourself, there are also predefined kirafunctions. You call these in the same way as normal functions: precede the name by the kirachar (this is by default) and add the parameters between (these) round brackets. For more information about kirafunctions, see the section about those. Examples: > #var counter {} > #function counter {#var counter \counterI} > #disp {counter()} > #disp {counter()} > #disp {counter()} > #disp {Counting... counter() counter() counter()} > #function first {#disp {Arguments are: <:>};;#var first <0>} > #disp {first(a,b,c)} This will first display all the arguments, but result with only the first argument (a). > #function first This should show you the value of the function we made. > #del function first This removes the function we just made. > #function This shows the functions you have made so far, as well as all the predefined functions. > #function KIRA This shows only the predefined functions. > #function USER This shows only the user functions. > #del function KIRAampm We can remove kirafunctions as well. :) ------------- +++ GOTAB +++ ------------- Syntax: GOTAB [tabnr | tabname | NEXT | PREV] Explanation: This command activates the given tab. This command is best used in keybindings (for example alt+1 to go to the first tab etcetera). Note that tabnumbers start at 0, not 1. For a basic explanation about tabs / the windowsystem, read the section about it in 'overview'. Example: > #disp {some spam to recognise the current tab as tab 0} > #tab add (You are now at tab 1!) > #tab (Shows you some information about the current tabs) > #gotab 0 > #send 1 {#disp {Look, back at tab 1!}} > #gotab next > #gotab next (Back at tab 0) ------------ +++ HELP +++ ------------ Syntax: HELP HELP subject Explanation: Without arguments, this commands gives a small introduction to the helpsystem and a list of useful helpfiles. When a subject is given, the information about this subject is loaded. All information is read from the file help.txt which should be in the same folder as kira.exe Most of the helpfiles match the explanation in this manual, although some are shortened / split up over several helpsubjects to enable reading without (too much) scrolling. All helpsubjects on commands use the same standards to describe syntax, the same as the ones used in this file: - the command is given in capitals - arguments to be entered literally are also given in capitals - arguments that must be replaced with some text of your own are in normal script - optional arguments are given in brackets - a choice between several arguments is given in square brackets, where the choices are separated by bars. - text in green points to a specific helpfile, setting or command. Examples: Above, we see: Syntax: HELP HELP subject This means you can either use the 'help' by itself (preceded by the kirachar) > #help or use help with as argument a subject you want help about > #help commands A more complete example is given by the syntax on 'tab': Syntax: TAB TAB ADD TAB DEL TAB SET [MAIN | ECHO | INFO | KIRA] window You can either use tab by itself > #tab add a new tab in two ways > #tab add > #tab add mytab delete a tab > #tab del > #tab del mytab or give a window a special property > #tab set echo 0 > #tab set info infowin mytab Note that the above examples are likely to produce errors if you execute all of them, since I just used them to demonstrate correct syntax. ------------- +++ INPUT +++ ------------- Syntax: INPUT INPUT MOVE Explanation: Without arguments, this will show you the positions of the inputwindows on all your tabs. The INPUT MOVE syntax enables you to move the inputwindow to a different position and/or resize it. If y_ul is left empty, the prompt is placed at the bottom of the screen (no matter what the height is). x_ul is defaulted 0, width is defaulted to 100%-x_ul and height is defaulted 1. If you want a default value for any of the arguments but not for the next, you can leave it empty using {} instead of an argument. Note that this command is best used in combination with other windowmanagement commands. Moving the inputwindow alone will not move any other windows, so overlap will occur, which will make it all look messy. x_ul, y_ul, width and height are all expected to be of the form A%+B or A%-B (where A and B are numeric). Spaces in this combination are not allowed. For example x_ul = 9%+3 will put the left of the window 3 columns away from 9% of the total screenwidth. 100% is the total number of rows / columns, and the first is numbered 0; therefore, if you want to place something at the bottom or right of the screen, it must be placed at 100%-1. Please note that in the widgets version, the given width and height might not be the actual number of columns and rows that fit the window. Usually, it will only fit more characters than specified; if your inputwindow has width smaller than 5, it might fit less. Examples: To make the inputwindow in the standardconfiguration have 2 lines: > #window resize win0 100% 100%-3 > #line move mainline 0 100%-3 > #input move 0 100%-2 100% 2 To move it to the top from this situation: > #line move mainline 0 2 > #window move 0 0 3 > #input move 0 0 100% 2 ---------------- +++ KEYCHECK +++ ---------------- Syntax: KEYCHECK Explanation: Using the command > #keycheck places you in keychecking mode. If you press any key, its keycode will be printed to your main window. You can leave keychecking mode by typing escape. In some versions you may have to press escape twice, or wait a few moments after the first press. Finding a keycode is often needed to create keybindings. Sometimes it may happen that a keypress generates two separate keycodes. Be on your guard for this. It may also happen that two different keys give the same code. If you are testing keys where this might be the case (the numpad is an example for both above described events), also be careful for this. It may be a good idea to test whether some likely keys produce the same code. --------------------- +++ KEY_BACKSPACE +++ --------------------- Syntax: KEY_BACKSPACE Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing backspace is executed: the character before the cursor in the inputwindow is deleted, or the selection if anything is selected. If the cursor is at the beginning of the inputwindow, the command doesn't do anything. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! ------------------ +++ KEY_DELETE +++ ------------------ Syntax: KEY_DELETE Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing delete is executed: the character after the cursor in the inputwindow is deleted, of the selection if anything is selected. If the cursor is at the end of the inputwindow, the command doesn't do anything. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! --------------- +++ KEY_END +++ --------------- Syntax: KEY_END Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing end is executed: the cursor is placed at the end of the inputwindow. Any selection is unselected (unless selectionmode is active - see the section about KEY_TOGGLESELECT for more information). This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! ----------------------- +++ KEY_HISTORYDOWN +++ ----------------------- Syntax: KEY_HISTORYDOWN Notes: This command will never be echoed. Explanation: This command makes the inputwindow move one place down in history: when this command is executed, the inputwindow will contain the next command. To be more exact: the inputwindow remembers a list of typed commands. Even commands that were abandoned by using either KEY_HISTORYDOWN or KEY_HISTORYUP are included in this list (together with all executed commands). The list has limited size, so old commands are forgotten. Empty commands are never remembered. While typing a new command, or altering an old one, the position in the inputwindow is -1. If KEY_HISTORYDOWN is executed in this situation, the history scrolls up; the command being typed is saved on historyposition 0 and the cursor will go to a new, empty line. If KEY_HISTORYDOWN is executed when the position is not -1, the position will simply be lowered by 1 and the command at that position is loaded into the inputwindow. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. --------------------- +++ KEY_HISTORYUP +++ --------------------- Syntax: KEY_HISTORYUP Notes: This command will never be echoed. Explanation: This command makes the inputwindow move one place up in history: when this command is executed, the inputwindow will contain the previous command. To be more exact: the inputwindow remembers a list of typed commands. Even commands that were abandoned by using either KEY_HISTORYDOWN or KEY_HISTORYUP are included in this list (together with all executed commands). The list has limited size, so old commands are forgotten. Empty commands are never remembered. While typing a new command, or altering an old one, the position in the inputwindow is -1. When KEY_HISTORYUP is executed at any position, the position is increased by 1 and the relevant contents is loaded into the inputwindow. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. ---------------- +++ KEY_HOME +++ ---------------- Syntax: KEY_HOME Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing the home key is executed: the cursor moves to the beginning of the inputwindow. If selectionmode is active (see the section about KEY_TOGGLESELECT for more information) and the cursor is at the start of the current selection (or: there is no selection), this causes the selection to start at the new cursorposition. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! ------------------ +++ KEY_IGNORE +++ ------------------ Syntax: KEY_IGNORE Notes: This command will never be echoed. Explanation: This command causes the next keypresses to be ignored. The most usual reason to do this, is because a certain keypress triggers more than 1 keyevent. For example, the numpadkeys often give 2 keyevents (you can check this with KEYCHECK): a special numpadcontrolsequence, and the key with the number you pressed. However, feel free to use it in other ways :). This command is intended to be used in keybindings. The kira assistant can create keybindings for the numpad, covering the most important functionality of this. Examples: (assume numpad-6 causes keys 503 and 54 to be triggered) > #key_bind 503 {e;;#key_ignore} --------------------- +++ KEY_LEFTARROW +++ --------------------- Syntax: KEY_LEFTARROW Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing the left arrow key is executed: the cursor moves one place to the left, if possible. If selectionmode is active (see KEY_TOGGLESELECT for more information) this will cause the not unusual effect of pressing shift + leftarrow: the selection will now start or stop at the new cursorposition. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! ------------------ +++ KEY_RETURN +++ ------------------ Syntax: KEY_RETURN Notes: This command will never be echoed. Explanation: Executing this command is equivalent to pressing return. It is not needed to bind this character to your return. Kira will recognise the return key automatically. However, it can be usefull if you have a small return and keep pressing the key next to it, for example. ---------------------- +++ KEY_RIGHTARROW +++ ---------------------- Syntax: KEY_RIGHTARROW Notes: This command will never be echoed. Explanation: When this command is executed, the usual effect of pressing the right arrow key is executed: the cursor moves one place to the right, if possible. If selectionmode is active (see KEY_TOGGLESELECT for more information) this will cause the not unusual effect of pressing shift + rightarrow: the selection will now start or stop at the new cursorposition. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. In the graphical version of the program, this key is automatically handled and thus will generally not need to be bound! -------------------- +++ KEY_SCROLLUP +++ -------------------- Syntax: KEY_SCROLLUP Notes: This command will never be echoed. Explanation: This command is normally used without any arguments; this will make the main window of the current tab go into scrolling mode (where the window is split if it is large enough), and the upper part of the window is scrolled up by its size minus 1. Generally, when this command is executed, the given window (defaults to the tab's main window), if it isn't in scrolling mode, will split at the given breakpoint, and a line will be placed there. A breakpoint can be given in the form A%+B, but this is relative to the given window rather than the tab - if no breakpoint is given, then it will be assumed 50%. If the window is already split, supplying a new breakpoint will not make a difference. Now the window is in scrolling mode, the upper part of the window is scrolled up by lines. Lines may also be given in the form A%+B, which is again relative to the window. If tab is not given, it is assumed as the active tab. The scrollwindow (the upper part of the split window) has a fixed memory: you can not scroll up indefinately, and if text is added to the main window, it will not be added to the scrollwindow. As a consequence, the scrollwindow can also be used to fix text, for example for copying purposes. If the window is too small to be split properly, this command will instead scroll it up by its height. A bright "v" in the bottom line will indicate that the window is overlapped completely by its scrollwindow. Note that if this is the case, no text in the window will not be shown! This command is intended to be used in keybindings. The kira assistant always creates a keybinding for scrolling up the default number of lines. A not uncommon use would be to bind page up to KEY_SCROLLUP, and shift + page up to KEY_SCROLLUP 2, for example. Examples: > #key_scrollup This will scroll the main window on the current tab up by almost its own size, or split the window and scroll it up so the bottom line of the split window is what used to be the top line of the window. > #key_scrollup 50%-2 {} 50% This will do exactly the same! This because the split window, including the line, is made 50% high, so scrolling up 50%-2 will scroll up the split window by its height minus 1 > #key_scrollup 1 Scrolls up the main window by 1 line. ---------------------- +++ KEY_SCROLLDOWN +++ ---------------------- Syntax: KEY_SCROLLDOWN Notes: This command will never be echoed. Explanation: This command is normally used without any arguments; if used when the main window of the current tab is active, it will scroll down its own size minus 1. If the scrollwindow was already scrolled down to its bottom, it is removed. Generally, when this command is executed and the given window (defaults to the given tab's main window) is in scrolling mode, there are two possibilities: - the scrollwindow has already scrolled down to the maximum of its memory; in this case, the split window will be removed, and the window itself will be shown fully again - the scrollwindow has not been scrolled down to its limit; in this case, it will be scrolled down by lines. Lines may be given in the form A%+B, where the percentage is taken relative to the height of the window scrolled (so not the scrollwindow or the tab!). Normally, you use for this the same as used in scroll_up. If the given window is not currently split, the command will not do anything. The scrollwindow (the upper part of the split window) has a fixed memory: you can not scroll up indefinately, and if text is added to the main window, it will not be added to the scrollwindow. As a consequence, the scrollwindow can also be used to fix text, for example for copying purposes. This command is intended to be used in keybindings. The kira assistant always creates a keybinding for scrolling down the default number of lines. A not uncommon use would be to bind page down to KEY_SCROLLDOWN, and shift + page down to KEY_SCROLLDOWN 2, for example. Examples: > #key_scrolldown This will scroll the main window on the current tab down by almost its own size, or remove it if we were already at the bottom. > #key_scrolldown 50%-2 This will do exactly the same! This because the split window, including the line, is made 50% high, so scrolling up 50%-2 will scroll up the split window by its height minus 1 > #key_scrolldown 1 Scrolls down the main window by 1 line. ----------------------- +++ KEY_SCROLLSTART +++ ----------------------- Syntax: KEY_SCROLLSTART Notes: This command will never be echoed. Explanation: This command is normally used without any arguments; this will make the main window of the current tab go into scrolling mode. This will cause the window to be split, and the scrollwindow (the upper part of the split window) will be scrolled down to the lowest part of its memory. Generally, when this command is executed, the given window (defaults to the tab's main window) will split at the given breakpoint, and a line will be placed there. A breakpoint can be given in the form A%+B, but this is relative to the given window rather than the tab - if no breakpoint is given, then it will be assumed 50%. The scrollwindow will have all the text from the normal window, and be scrolled down to its lowest part. If the window was already split, the old split will be removed first. The new scrollwindow will have the memory of the whole window, so including all text that was added after the first scrollwindow was started. If the window is too small to be split properly, all this doesn't really apply, as the window will not be split but instead scrolled up a bit. A bright "v" in the bottom line of the window will be used to indicate this. The scrollwindow has a fixed memory: you can not scroll up infinitely, and if text is added to the main window, it will not be added to the scrollwindow. As a consequence, the scrollwindow can also be used to fix text, for example for copying purposes. This command is intended to be used in keybindings. It is not likely you will really need it, as KEY_SCROLLTOGGLE will usually do what you need. Examples: > #key_scrollstart This will split up the main window in two parts, with a line in the middle. If you don't use #key_scrollup further, or get more text in the window, these parts will look exactly equal. > #key_scrollstart {} 5 Makes a scrollwindow for the main window on the current tab, but it will only have height 4 (5 = height 4 + 1 for the line). ---------------------- +++ KEY_SCROLLSTOP +++ ---------------------- Syntax: KEY_SCROLLSTOP Notes: This command will never be echoed. Explanation: Removes scrolling mode from the given window in the given tab. The window is defaulted as the tab's default window, the tab as the current tab. When scrolling mode is removed, the window will no longer be split. If it wasn't split in the first place, nothing will happen. This command is intended to be used in keybindings. It is not likely you will really need it, as KEY_SCROLLTOGGLE will usually do what you need. ------------------------ +++ KEY_SCROLLTOGGLE +++ ------------------------ Syntax: KEY_SCROLLTOGGLE Notes: This command will never be echoed. Explanation: If the main window is not yet in scrolling mode, this command has the same effect as KEY_SCROLLSTART: the window will be split in two, where the upper window can be scrolled using KEY_SCROLLUP and KEY_SCROLLDOWN. If the main window is in scrolling mode, this command will stop scrolling mode and remove the split window (just like KEY_SCROLLSTOP). This command is normally used without any arguments; this will make the main window of the current tab go into scrolling mode, with height half the parent window. Generally, when this command is executed, the given window (defaults to the tab's main window), if it isn't in scrolling mode already, will split at the given breakpoint, and a line will be placed there. A breakpoint can be given in the form A%+B, but this is relative to the given window rather than the tab - if no breakpoint is given, then it will be assumed 50%. If the window is already split, supplying a new breakpoint will not make a difference. If the window was already in scrolling mode, the scrolling will be removed. The breakpoint parameter will be ignored in this case. You don't have to use KEY_SCROLLTOGGLE to start or stop scrolling: scrollmode will also be started with KEY_SCROLLUP, and when using KEY_SCROLLDOWN long enough, the split window will also be removed. However, it may be convenient to temporarily open a split window to keep the current text from scrolling off the screen (for example for copy/paste purposes), or to close the scrollwindow at once after scrolling up a fair bit. If the window is too small to be split properly, all this doesn't really apply, as the window will not be split but instead scrolled up a bit. A bright "v" in the bottom line of the window will be used to indicate this. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. -------------------- +++ KEY_SIMULATE +++ -------------------- Syntax: KEY_SIMULATE key Notes: This command will never be echoed. Explanation: When this command is executed, the same effect will take place as when the given key was pressed. This may be useful in some aliases, or some keybindings where you want different keys to do the same without using aliases. Example: > hold staff;; #key_type {cast magic missile on victim} ;; #key_simulate 13 The above may be useful if you want to hold your staff and start casting magic missile (keeping the command selected in your inputwindow!) as soon as soon as something happens. ------------------------ +++ KEY_TOGGLESELECT +++ ------------------------ Syntax: KEY_TOGGLESELECT Notes: This command will never be echoed. Explanation: This command toggles selection mode on the input window. It is intended to be used in combination with other keycommands, but can also be bound by itself, which may be useful when you're working from a terminal that doesn't pass on many different characters. If selectionmode is active, the commands to move the cursor around (KEY_RIGHTARROW, KEY_LEFTARROW, KEY_HOME and KEY_END) will all change one of the bounds of the current selection from the place where the cursor used to be to the new position. This command is intended to be used in keybindings. You can use the kira assistant to create a keybinding for this. The assistant will also make bindings for the default combinations mentioned above, if your terminal can handle this. Examples: > #bind {316 16} {#key_toggleselect;;#key_leftarrow;;#key_toggleselect} > #bind {315 16} {#key_toggleselect;;#key_home;;#key_toggleselect} > #bind {331} {#key_toggleselect} ---------------- +++ KEY_TYPE +++ ---------------- Syntax: KEY_TYPE text Notes: This command will never be echoed. Explanation: After this command is executed, the inputwindow will contain the supplied text (not selected, as though you had typed it yourself). This may, for example, be useful in some aliases. Example: > abscond south ;; #key_type ambush -------------------- +++ KEY_WORDLEFT +++ -------------------- Syntax: KEY_WORDLEFT Notes: This command will never be echoed. Explanation: When this command is executed, the cursor will move to the first letter of the current word, or the first letter of the previous word if the cursor was already at the first letter (or at a space). If selectionmode is active (see KEY_TOGGLESELECT for more information), this will change the place where the selection starts or stops. Selectionmode will stay active. --------------------- +++ KEY_WORDRIGHT +++ --------------------- Syntax: KEY_WORDRIGHT Notes: This command will never be echoed. Explanation: When this command is executed, the cursor will move to the first letter of the next word. If selectionmode is active (see KEY_TOGGLESELECT for more information), this will change the place where the selection starts or stops. Selectionmode will stay active. ------------ +++ LINE +++ ------------ SYNTAX: LINE LINE ADD name x_ul y_ul width height LINE MOVE line x_ul y_ul LINE PRINT line info LINE DEL line Explanation: This command allows you to create, remove or write on a line on your screen. A line is basically a small field on your screen, used to separate the windows and inputwindow on your tab to make the whole thing look better. In the default configuration, this is the blue line near the bottom of the screen. LINE without further arguments gives you an overview of the current lines. For each line, this will tell you its number (relative to the tab it is on), which you need to delete or write on a certain line. Using LINE ADD you can add a new line. A line should either have a unique name on its tab, or an empty name (you can choose an empty name by setting name {}). You can have lines with the same name on different tabs; in fact, in the default configuration all tabs have a line named "mainline". Backcolour is the colour of the line, frontcolour the colour you use to write on it, attribute the attribute in which it is written, character is a letter the line will be filled with (which could, for example, be something like -), tab is the tab the line is to be added to. Valid colours are black, red, green, yellow, blue, magenta, cyan, white and default. Valid attributes are standout, bold, italic, underline, blind, dim, strikethrough (although not all of these actually have an effect yet). If not supplied, backcolour and frontcolour are both set to default, attribute to normal, character to a space and tab to the current tab. A backcolour "default" for a line gives it the standard text colour (white in standard colour settings, but can be changed with the COLOUR command), a frontcolour default makes the letters on the line have the usual backgroundcolour (black in standard colour settings). x_ul, y_ul, width and height are all expected to be of the form A%+B or A%-B (where A and B are numeric). Spaces in this combination are not allowed. For example x_ul = 9%+3 will put the left of the window 3 columns away from 9% of the total screenwidth. 100% is the total number of rows / columns, and the first is numbered 0; therefore, if you want to place something at the bottom or right of the screen, it must be placed at 100%-1. LINE MOVE allows you to move a line to a different position. If width and height are included, these define the new size; otherwise the old width and height are used. Using LINE DEL you can remove the given line (given either by its number or name, as showed when typing "#line"). If no tab is given, the current tab is assumed. You can also print useful information on a line: use LINE PRINT for this. Tab, again, is assumed to be the current tab if you don't give an argument. Printing on a line will overwrite the current text on that line. Again, you can give a line by its number or name (relative to the given tab, or the current tab if not tab is given). Printing on a line will be done in the line's foregroundcolour, but without any attributes; if you want to use different colours and attributes, use ansi sequences (as explained in the section for the DISP command). Please note that the value on a line will never be updated unless you write on it again. Also note that, while it's possible to have a line overlap with a window, windows are considered more important and thus are on top. Examples: > #window resize 0 100% 8 > #window move 0 0 10 This moves the window out of the way so you can see the next few examples! > #line add {} 0 4 100% 1 white black normal {\ } 0 This will create a full-width, white line in the 5th row on your screen, filled with spaces, on the first tab. > #line add {} 1 0 100%-2 1 default green bold - This will add a line consisting of bold green stripes on the standard background colour; to be cute, it misses the first and last column. > #line add mainline 0 1 100% 1 This would create a standard line just below the green one, but it won't work, since we already have a line named mainline on this tab! > #line Assuming you started with default configuration (which has one line), this should show you 3 lines, the last added having number 2 and no name. > #line del 2 0 Now there's only 2 lines left. > #tab add > #gotab 0 Now you have 2 tabs, but you're back at the first one. Check the current lines: > #line This should show you there's a line named "mainline" both on the first and second tab, which also has number 0. That's not a problem because they're on different tabs. :) > #line print 1 {Testing!} > #line print mainline {Tab 0} 0 > #line print mainline {Tab 1} 1 This should print the text "Testing!" on the white line, and the blue lines on each tab will show the number of the tab. > #line print 1 {Another test.} 0 This overwrites the text on the white line. A basic explanation on the windowsystem is given in the "overview" section. ------------ +++ LOAD +++ ------------ Syntax: LOAD filename Explanation: This command tells kira to load the given file. All commands in the file will be executed one by one, as though you were giving them through the inputwindow, with the exception that they won't be echoed, nor will the program give feedback messages, regardless the current state of the variables showInformation, echoKiraCommands and echoMudCommands. Not even commands in a doEcho. If you are determined, you can give yourself information using the DISP statement. If you don't give the full path, kira will try to load the file from the program's own directory. ----------- +++ LOG +++ ----------- Syntax: LOG LOG [HISTORY] PLAIN file LOG [HISTORY] COLOUR file LOG STOP LOG STOP ALL Explanation: This command allows you to log all the text that is printed on a given window to a file. You can either log in plain text (throwing away all colour information), or in colour (this will create an HTML logfile). At the moment it is not yet possible to add the history of the window into the logfile. LOG without arguments gives an overview of your current logfiles. Each logfile has a window (the window it is logging) and an index on this window (which can be higher than 0 if you have more logfiles - this could be useful, for example, if you always have a plain logfile running, but want to add a colourlog for a special occasion). You need both to close a specific logfile. LOG PLAIN will start logging the text on the given window (which is defaulted to the main window of the active tab) to plain text - all colour information is ignored. If you include the HISTORY tag, all text that is currently in the window's history is included in the log as well as new text. LOG COLOUR will start logging the text on the given window to an html document. Colour information will be stored using css. Here, too, the HISTORY tag makes the log include all text that's currently in the scrollback. LOG STOP will close the logfile identified by the given window and index. If no index is given, the last made logfile on the given window is assumed. If no window is given, the main window of the active tab is assumed. Note that when closing a logfile, the indices of later logfiles on the same window will change. As such, when you have two logs on the same window, closing them using "#log stop 0 0;;#log stop 0 0" is alright, but "#log stop 0 0;;#log stop 0 1" is not. If you give LOG STOP an argument ALL, all open logfiles will be closed. If you delete a window (or close kira), all its logfiles will also be closed. A logfile will always be saved before closing. If you do not use the window system, the window argument can be ignored; either leave it out or use "0". For more information on the windowmanagement system, check the section in overview. Example: > #log plain {/home/me/.kirafiles/mud_KIRAdatetime(short)} This will start a logfile named after the current time in the folder /home/me/.kirafiles/. Read the section on kirafunctions in the overview for more information about the used function. > #log colour {/home/me/speciallogs/wedding.log} This will add a colour logfile over the existing one. > #log This should show you you have 2 logfiles running. > #log stop 0 0 This stops your plain log, assuming you did all this on the first window. > #log This should show you you have 1 logfile open. > #log stop all This closes the last logfile. -------------- +++ NOECHO +++ -------------- Syntax: NOECHO command Notes: This command will never be echoed. Explanation: This command forces text not to be echoed. Even if this command is placed within a #doecho. Basically, this commands sets the settings echoKiraCommands, echoMudCommands and showInformation to false while executing the command. As a consequence, changing the settings echoKiraCommands, echoMudCommands and showInformation will only have a short effect, as those settings are reset after the command. Examples: > #set echomudcommands true > echoed > #doecho {not echoed!} > #noecho{#doecho{echoed!}} > #doecho{#noecho{not echoed!}} > #set echomudcommands false > #noecho {#set echomudcommands true ;; test test} ;; retest ------------- +++ PASTE +++ ------------- Syntax: PASTE PASTE [START | STOP] Explanation: This command will allow you to go into pasting mode and back. This is intended for use in the linux terminal version, where you can paste large amounts of text with a single mouseclick. When in pastemode, commands you give in the inputwindow will not be remembered. Using PASTE without arguments will toggle pastemode. In the graphical version, pressing ctrl+v will automatically enable pastemode, paste what's on the keyboard, and then put it back to what it was. As such, pasted text will generally not be remembered by the inputwindow. ------------- +++ RESET +++ ------------- Syntax: RESET RESET [ALIAS | VAR | FUNCTION | BIND | WALKCHAR | TAB] Explanation: Use this command to delete all your current aliases, variables, functions, macros and/or walkcommands. RESET TAB and RESET will also reset the entire windowsystem: all tabs without an open connection are removed (except the first tab), all windows are removed and all remaining tabs are given the standard setup (1 outputwindow, inputwindow at the bottom, and a blue line between them). While all connections stay open, the history is wiped from the windows, and all logfiles are closed. ----------- +++ SET +++ ----------- Syntax: SET SET setting SET setting value Explanation: Use this command to change or view your current settings. Using set without arguments (or argument all) will give you an overview of all your current settings. Using set followed by a setting will show you the current value of that setting. Using set followed by a setting and a value valid for that setting, will change the value of that setting. Example: > #set -> gives a nice list > #set indent -> "indent : 2" > #set indent 4 -> "Okay, indent set to 4." More information about settings can be found in the settings overview. ------------ +++ SEND +++ ------------ Syntax: SEND tab command Explanation: This executes the given command as though it was sent on the given tab. The send command will be echoed on the main window of the current tab, and the command itself will be echoed on the window where it's executed (if you don't want this, use #noecho in the command to avoid it being executed). Note, however, that when used in an alias, it will not be echoed if you have the setting expandaliases set to false (as it is by default). If you want something echoed despite this, use #doecho! Example: > #tab add > #send 0 {#disp {This is displayed on the first tab!}} > #gotab 0 --> You should now see the displayed message. Ignore for now that this could also be done immediately with the disp command. ;) > #alias #send {#SEND <0> {#noecho{<1:>}}} > #send 1 {#disp {This won't echo on tab 1!}} > #gotab 1 --> This only shows the displayed text, not the command (on tab 1). -------------- +++ SYNTAX +++ -------------- Syntax: SYNTAX subject Explanation: This command reads the information about the given subject from the file help.txt, which should be in the same folder as kira.exe, and displays the syntax part. The syntax is given in exactly the same way as the syntax part in the sections in this file. All helpsubjects on commands use the same standards to describe syntax, the same as the ones used here: - the command is given in capitals - arguments to be entered literally are also given in capitals - arguments that must be replaced with some text of your own are in normal script - optional arguments are given in brackets - a choice between several arguments is given in square brackets, where the choices are separated by bars. Examples: > #syntax tab gives the following result: TAB TAB ADD TAB DEL TAB SET [MAIN | ECHO | INFO | KIRA] window You can either use tab by itself > #tab add a new tab in two ways > #tab add > #tab add mytab delete a tab > #tab del > #tab del mytab or give a window a special property > #tab set echo 0 > #tab set info infowin mytab Note that the above examples are likely to produce errors when executed, since I just used them to demonstrate correct syntax. ----------- +++ TAB +++ ----------- SYNTAX: TAB TAB ADD TAB DEL TAB SET [MAIN | ECHO | INFO | KIRA] window Explanation: This command allows you to handle your tabs. As explained in the section about the window system in the overview, a tab is your workspace. It's what you see when you open the program: everything. Read that section for a better explanation of what a tab is used for. A tab typically contains a prompt (inputwindow), a textarea (outputwindow) where the text you typed and received from the mud goes, and a line to separate the two. However, this is merely default configuration: you can add more windows, add or remove lines and move everything to whichever obscure positions you can think of! :) However, there is only one connection per tab. You need to add a new tab to have more connections. TAB without arguments shows you a small overview of the currently existing tabs. Note that every tab has both a number and a name which it can be referred by. The overview will also show you which windows have certain functionality in every tab (the tab's main window, echo window and info window). What these do is explained below. TAB ADD allows you to add a new tab. This tab will automatically be activated. If you don't give a name to refer to this window with, kira will choose a name for you. The name may not be numeric, as each tab also has a number. TAB DEL allows you to remove a tab. Without an argument, the current tab is deleted, otherwise the given tab (which may be referred as either its name or its number, as shown by TAB without arguments). If you only have one tab, you can not delete it. TAB SET specifies the functionality of a given window in your tab. If you have several windows, you can use different windows as MAIN (here the text from the mud gets printed), ECHO (shows all your commands, assuming the settings echomudcommands or echokiracommands are true), INFO (shows informative messages and warnings from kira) or KIRA (shows text printed by kira, for example helpfiles). Again, if tab is not given, the current tab is assumed. Note that it is not necessary to choose a window that is on this tab to set it as one of the defaults. Examples: > #tab add newtab This creates a new tab. You are now at the new tab. But no worries! You can go back using: > #gotab prev Now, to find out what tabs and windows we have: > #taboverview We will use the window in the other tab to echo our commands and information. > #tab set echo win1 > #tab set info 1 0 To see our last commands, go back to the other tab. > #gotab 1 To conclude, delete this tab. This will also delete the window, so the echo and info window of our first tab will be set back to its own main window. > #tab del ------------------- +++ TABOVERVIEW +++ ------------------- SYNTAX: TABOVERVIEW Explanation: This command will give you an overview of your current tabs, windows and lines. It is similar to the output of TAB, WINDOW and LINE, and shows all of these. More information can be found in the sections about tabs, windows and lines, as well as in the windowmanagement overview. ------------- +++ TIMER +++ ------------- SYNTAX: TIMER <[tab|ALL]> TIMER name interval command Explanation: With this command, you can set up a timer, or get an overview of all the existing timers. Without arguments, TIMER gives the timers on the current tab. When a tab is given, the timers of thab tab are shown, or with argument ALL, the timers on all tabs are displayed. The second syntax is used to create timers: the name has to be either unique (on the given tab, it's allowed to have similarly named timers on different tabs!) or empty, the interval is in seconds, and the command will be parsed (again) every time the timer is run. If you don't supply a tab, the timer is made on the current tab. A timer is bound to a tab, and will always run on that tab, rather than the tab that is currently active. A timer does not get removed automatically, unless the tab it is on is removed. To delete a timer, simply use the DEL TIMER timer syntax, where for "timer" either the name of the timer or a number indicating the index (from the list given by the plain timer command) is given. Examples: > #timer clock 60 {\[#noecho{#line print 0 {[KIRAhour():KIRAminute()]}$}} > #timer once 300 {#beep;;#del timer once} -------------- +++ UPDATE +++ -------------- SYNTAX: UPDATE Explanation: Without arguments, this command will just force an update on the screen. If something has overwritten a part of the tab without notifying kira, this may sometimes be necessary (particularly in the linux versions). When arguments are given, these may change the screensize. This is intended for those versions that do not determine the terminalsize automatically, and generally shouldn't be necessary. In the versions that can detect the terminalsize themselves, this either will not have an influence, or will change back if you resize the screen. ----------- +++ VAR +++ ----------- SYNTAX: VAR VAR varname VAR varname value Explanation: A variable is basically a way to (temporarily) remember a value. Since triggers and calculation are not yet implemented, this finds its use mostly in aliases. A variable has a name and a value. You can create / change a variable with the VAR command, and expand it by preceding its name with a$ (or whatever you set the variablechar to).

VAR without an argument or with argument ALL shows a list of all
current variables.

VAR followed by a single text shows a list of all variables in
value.

VAR followed by a name and some value (which should be given as one
argument, so either a single word, or in {curly brackets}) will
create a variable with the given name and value.
When using $varname in another text, this will be replaced by the value of the variable with name "varname" instead. Examples: Create a variable named myvar, and immediately echo it. > #var myvar {hello world!};;#disp {$myvar}

A slightly more useful example is seen in combination with an alias.
> #alias trg {#var target {<0=\$target> <1:>}} > #alias kk {trg <:>;;kill <0=\$target> <1:>}
To see what this does:
> #set expandaliases true
> kk hublandish barbarian
> kk

------------
+++ WALK +++
------------

SYNTAX:
WALK walkstring

Explanation:
A walkcommand is used for quickwalking. This way you can make
one-line-aliases to walk through the whole mud, for example. You
can also use it to quickly use given directions.
To use walkcommands, you first have to bind each command you want
to use in a quickwalk to a char (using the WALKCHAR command).

Then you can make a walkstring consisting of combinations
(number)(char) or (char), where char is one of the characters bound
using WALKCHAR. (char) is actually short for 1(char).
When calling WALK with this walkstring, for each (number)(char)
combination, the command bound to (char) will be executed (number)
times.

Note that, while this command is intended for quickwalking, its use
is not necessarily limited to this. However, since the commands this
is used for are assumed to be relatively simple (like "north"), they
will not be remembered with complete parsing information. You have
been warned.

Examples:
First, create some walkchars:
> #walkchar n north ;; #walkchar e east ;; #walkchar s south
> #walkchar w west ;; #walkchar r northeast ;; #walkchar u up
Now the following will make you go south twice, e 5 times,
northeast, east, 2 more northeast, north, and twice west. Then
"read sign" will be sent and you will walk up and south, and
execute "join".
> #walk 2s5ere2rn2w ;; read sign ;; #walk us ;; join
Note that numbers are used to execute a certain walkchar several
times.

----------------
+++ WALKCHAR +++
----------------

SYNTAX:
WALKCHAR
WALKCHAR char
WALKCHAR char command

Explanation:
WALKCHAR without argument will give you an overview of your current
walkchars.

WALKCHAR followed by a single character will show you the command
associated with that letter (assuming there is one).

WALKCHAR followed by a character and a command will bind that char
to the given command for use in a WALK statement.
If (number)(thatchar) occurs in a walkcommand, the bound command
will be executed.
A walkchar must be a single character.

section. :)

Example:
First, create some walkchars:
> #walkchar n north ;; #walkchar e east ;; #walkchar s south
> #walkchar r northeast
And this is how we use them:
> #walk 14s4eren
This will make you go 14 times south, 4 times east, and then
northeast, east, north.

--------------
+++ WINDOW +++
--------------

Syntax:
WINDOW
WINDOW COPY window tab
WINDOW RESIZE window   [|ALL]
WINDOW MOVE window x_ul y_ul
WINDOW DEL window
WINDOW COLOUR window back front

Explanation:
A window is a textarea in your tab. It is not, like some would
imagine, the frame that contains your program - it is the part of
the tab where text from the mud, warnings and such are printed to.
Read the section about the window system in the overview and HELP
TAB for a more complete explanation of what a window is, exactly.
This section will explain what you can do with it.

WINDOW without arguments will give you an overview of your current
windows. This will show, for each window you have, a unique number
and a unique name, along with some information about the position.
You will need the window's name or number to refer to it with any
of the other WINDOW commands.

WINDOW ADD will create a new window (but not remove any of the old
ones). If name is not given, it is defaulted empty; tab is defaulted
as the current tab. x_ul and y_ul are set to 0 if not supplied,
width to 100% minus x_ul and height to 100% minus y_ul + 2 (leaving
2 rows at the bottom of the screen for the inputwindow). If you want
the default setting for some, but not all, of these, just give an
empty argument ({}).
A new window, with the given name, will then be created on the given
tab. The position and size are as supplied. If this overlaps with
other windows, things may start looking a bit messy - it is your own
responsibility to deal with this (delete or resize other windows,
for example). If you want to abuse overlapping windows, it is of
course your own choice - I give no guarantees about what windows
will be on top. Lines do go below all outputwindows, as well as
below the prompt.
Note that all coordinates start at (0,0), in the upper left (ul)
corner of the screen. For the rest, both coordinates and sizes can
be supplied in the form A%+B or A%-B (with A and B numeric, and no
spaces in this combination). Percentages are relative to the size
of the screen, and rounded down to whole rows / columns.

WINDOW COPY will copy the given window to a new tab. A window may be
visible on several tabs (although on each tab only once!). You could
use this, for example, when you have 2 connections open in different
tabs, but want to see the last few lines of what happens in the
other tab.
When you copy a window to another tab, you can also change its size
and coordinates on the new tab.
If you don't give values for x_ul, y_ul, width and/or height, these
values are taken from the first occurence of the window.
The parameter "window" must be adressed as either the number or the
name of the window you want to copy.
The copy of the window will be considered *the same* window, and
will also have the same name and number. Anything that is added to
one of the copies is added to all of them. You can also resize and
delete them all at once.

With WINDOW RESIZE you can resize a window (adressed by either its
number or its name).
If you have several copies of the window (made with WINDOW COPY),
you can change the width and/or height of either all of them, or
just one. In the latter case, you should also give the name or
number of the tab on which you want to change this window's height.

Use WINDOW MOVE to change a window's coordinates. Using this, you
can change the position of the upper left corner of a window. You
can not use it to move the window to another tab (to do this, copy
it to the other tab and delete the original).
The argument "tab" is to adress which instance of this window you
want to move, which may be useful if you have made several copies.
If no argument is given, the active tab is assumed.

WINDOW DEL will delete the given window, either from the given tab
if one is given, or from all of the tabs in the program if no tab is
given. Note that you can not delete a window if it's the only one
you have. It is generally not a very good idea to delete the only
window a given tab has either.

Using WINDOW COLOUR you can change the fore- and backgroundcolours
for an individual window. To change the colours for *all* windows,
use the COLOUR command.

For ADD, COPY and RESIZE, please note that in the widgets version,
the given width and height might not be the actual number of columns
and rows that fit the window. Usually, it will fit more characters
than specified; if your window has width smaller than 5, it might
fit less.

Examples:
This example will be utterly useless, but might demonstrate some of
the ways to use the window system.
First of all, add another tab to play with, and configure your keys
to switch tabs easily.
> #keycheck
Press F1 or ctrl+1 or esc+1 or whatever key/combination you want to
use for going to your first tab. If it gives a result, go on to
press F2, ctrl+2 or whatever you want to use for going to your
second tab. When you have that, press ctrl+tab or whatever you want
to use for going to 'the next tab' (where 'next' is considered
circular). Remember all results. Then press escape.

In the following, replace "27 49" by the result of the first
key(-combination), "27 50" by the result of the second one, and
"27 9" by your alternative for ctrl+tab.
> #bind {27 49} {#noecho{#gotab 0}}
> #bind {27 50} {#noecho{#gotab 1}}
> #bind {27 9} {#noecho{#gotab next}}
Now you can go to whichever tab you like by pressing the right
combination, and the command to do so won't even be echoed!
From now on, I will assume you can work with this. So if I say
'go to tab 0' (tab 0 being the first tab), I mean you should either
press ctrl+1 or whatever key(-combination) you set the first command
to, press ctrl+tab if you are in tab 1 (the second tab), do nothing
if you are in tab 0, or type something like #gotab 0.

Go to tab 1. First check which windows we have:
> #window
This should show that we have two windows, the one on tab 0 being
named "win0". Delete the window on the current tab.
> #window del 1
Now copy the window from the main tab to here, but with some place
spared at the top.
> #window copy win0 1 {} 1 100% 100%-3
Also make the window on tab 0 a line smaller:
> #window resize win0 100% 100%-3 0
> #window move win0 0 1 0
If you now switch between tabs 0 and 1, they look exactly the same.
To see some difference, add lines showing what tabs we're on at the
top of the screen:
> #line add tabline1 0 0 10% 1 green white normal \  0
> #line print tabline1 {tab 0} 0
> #line add tabline2 10% 0 10% 1 blue white normal \  0
> #line print tabline2 {tab 1} 0
> #line add tabline1 0 0 10% 1 blue white normal \  1
> #line print tabline1 {tab 0} 1
> #line add tabline2 10% 0 10% 1 green white normal \  1
> #line print tabline2 {tab 1} 1
Ooooh, now doesn't that look pretty?

Okay, on to something completely different and even more useless... Close the
client and reopen it, to go back to default configuration.
Let's add a cute little window and fill it. First, shrink the main window so
the new one will be visible.
> #window resize win0 100% 50%
> #window add echowin 50%-10 50%+1 20 5 tab0
> #tab set echo echowin
> 012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789
Now copy it to tab 1, just outside the screen, to see what happens!
> #window copy echowin 1 -10 -5 20 10
Now go to tab 1 and admire the result. :)