=====================================================================
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.
=====================================================================
About this document
-------------------
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.
2. About this document: this section, gives an overview of what the
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
(although menu's might be added in the graphical versions).
- 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
- loading information from files
- 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.
- Download the source and save to its own directory. Copy
CURSES_version.h to version.h and CURSES_Makefile to Makefile .
- Type 'make'. With a little luck, this should work. :)
Ansi version, linux.
- Download the source and save to its own directory. Copy
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 dev-c++.
- Download a devpack for wxwidgets (the version I used can be found at
http://www.upcase.de/devpack.html )
- Download the source and save to its own directory. Copy
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
instead of OS_WINDOWS.
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:
Download kira_win.zip. This will give you the file kira.exe, this
manual, a helpfile help.in and some basic inputfiles. Unzip them
together in some folder, like C:/program files/kira. Make a
shortcut from your desktop or start menu to kira.exe
If you have some version of linux:
Download kira_curses.tar.gz. This will give you the file
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
file. Download help.in (and manual.txt if you want to have the
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:
I'm not really sure about this. :S The wxwidgets version should
work if you have the right libraries - make sure version.h defines
only VERSION_WIDGETS and OS_LINUX (which hopefully makes the
network handling work). You can download the full source, and
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:
Run the program, by pressing your desktop shortcut, start menu link
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:
Now, I bet you didn't go to the trouble of downloading a client to
do exactly the things you can do with telnet, and have a nice
inputwindow. Kira also supplies keybindings, aliases, and much more
(for more information, check the commandlist). Try, for example,
'#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
add all your aliases, keybindings, autoconnects and messages you
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
aliases like loadchar1 that resets, reloads basic.in, and then
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.
Some more information that may be useful:
- 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
is taken literally. For more information, see the section about
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
your mud, type \####.
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
(assuming your kirachar is #).
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
#load basic.in
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
#load {file1}
#load {file2}
...
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
and keybindings associated with your first character on your mud),
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:
#alias char1 {#reset;; #load kira.in;; #load char1.in}
#alias char2 {#reset;; #load kira.in;; #load char2.in}
+++ 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.
Aliases also accept arguments. Read the section about aliases if
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
section about them :)
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
mud. For more information about this, read the section about 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
corresponding variable is pasted instead.
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
worrying too much about variables.
~ (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
added this :)
If you intend to use these combinations, and know a bit about
programming, I would recommend reading the complete explanation
on parsing, given below. This will probably help you debug your
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.
5. Return to point 1.
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
memory that start with the given text, along with their current
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.
For more information on how walkcommands work, see the above
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 ADD
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.
> #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.
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. :)
Download
Documentation
Forums