File: kildclient.xml

package info (click to toggle)
kildclient 2.5.0-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 5,540 kB
ctags: 1,595
sloc: ansic: 21,480; xml: 6,112; sh: 4,000; perl: 2,134; makefile: 178; sed: 16
file content (7930 lines) | stat: -rw-r--r-- 288,550 bytes
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<!-- $Id: kildclient.xml,v 1.102 2006/08/10 14:49:24 ekalin Exp $ -->
<book>
<bookinfo>
  <title>KildClient Manual</title>
  <subtitle>Version 2.5.0</subtitle>
  <author>
    <firstname>Eduardo</firstname>
    <othername>M</othername>
    <surname>Kalinowski</surname>
  </author>
  <copyright>
    <year>2004-2006</year><holder>Eduardo M Kalinowski</holder>
  </copyright>
</bookinfo>


<part><title>KildClient User's Guide</title>


<chapter><title>Introduction</title>

<para>KildClient is a MUD Client written with the GTK+ windowing
toolkit. It supports many common features of other clients, such as
triggers, gags, aliases, macros, timers, and much more. But its main
feature is the built-in Perl interpreter. You can at any moment
execute Perl statements and functions to do things much more powerful
than simply sending text the the mud. Perl statements can also be run,
for example, as the action of a trigger, allowing you to do complex
things. Some built-in functions of KildClient allow interaction with
the world, such as sending commands to it.</para>

<para>This manual will guide you in using KildClient. First the basic
usage will be described, and then more advanced features will be
explained. In the end, there is a reference of all built-in functions
of KildClient, which can be called from your scripts.</para>

<para>It is assumed that the user has some basic knowledge of MUDs and
their working, and also of the specific MUDs the users connects to.
This manual has no aim at explaining how to play a MUD. Even when
specific examples are given of commands, these might not work on all
MUDs.</para>

</chapter>



<chapter id="chap:running"><title>Running KildClient</title>

<para>To run KildClient, type <command>kildclient</command> in your
command prompt:</para>

<cmdsynopsis><command>kildclient [-c DIR] [World...] &amp;</command></cmdsynopsis>

<para>The ampersand (&amp;) at the end of the line means that the
command is to be executed in background, that is, not to wait until it
finishes to get another command prompt. Since KildClient is a GUI
program that does not require any input from the terminal, this is the
desired behaviour.</para>

<para>You can enter the name of one or more saved Worlds in the
command line, to have these Worlds opened automatically. If the World
name contains spaces, you will need to quote it to prevent it from
being interpreted as two or more names. The exact way depends on your
shell, but generally enclosing it in quotes should work.</para>

<para>If the <literal>-c</literal> (or <literal>--config</literal>)
command line option is given, its argument is treated as the name of a
directory to use to store configuration files and saved worlds. If it
is not given, the default is <filename>~/.kildclient</filename> under
Linux or <filename>kildclient</filename> under the Application Data
folder under Windows.</para>

<para>Alternatively, you may start KildClient from a menu in your
Windowing Environment. The exact way to launch KildClient will then
vary, but it should be just a matter of finding the menu entry and
clicking on it, or perhaps just cliking in an icon somewhere.</para>

</chapter>



<chapter><title>Basic Usage</title>

<para>This chapter will describe the most basic and important things you
need to know in order to use KildClient. It is recommended that you
read this section throughly, as it will ease understanding of the next
chapters.</para>

<sect1 id="sec:world-selector"><title>Connecting to a MUD</title>

<para>When you launch KildClient (see <xref linkend="chap:running"/>),
you'll see a screen like this one below:</para>

<figure><title>When KildClient is first started, you are asked to
  connect to a world</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/firstscreen.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The screen shown when KildClient is first started.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>Before anything else, be aware that World is just a synonym for
MUD, and these two words will be used interchangeably in this
document.</para>

<para>The list of saved worlds may be empty, especially if this is the
first time ever KildClient is run.</para>

<para>You have two options: connect to a previously saved World, or
connect to a new one. To connect to a new one, you can either connect
direcly by typing the MUD's address and port in the boxes, or by
creating a new World.</para>

<para>Creating a new World is recommended because it allows you to
save options for that world, such as the font size or the colors used.
When you define triggers, aliases these will also be saved.</para>

<para>However, even if you connect directly, you can still customize
the World, and you have the option of saving it, so the difference
between the options is not so great.</para>

<para>To create a new World, press the button labeled
<guibutton>New</guibutton>. You'll be taken to the <emphasis>World
Editor</emphasis>, a dialog in which you can configure everything
about the World. We'll talk about the World Editor in <xref
linkend="chap:world_editor"/>. For now, fill in the
<guilabel>Name</guilabel>, <guilabel>Host</guilabel> and
<guilabel>Port</guilabel> fields, and click
<guibutton>OK</guibutton>.</para>

<para>To connect to a saved World, just select it and click the button
labeled <guibutton>Connect</guibutton>. Alternatively, you can
double-click the World in the list.</para>

<para>Sometimes you may see a little expander sign to the left of a
World's name, and when you click it some options appear inside that
World. This happens when there is more than one character associated
with that World (see <xref linkend="sec:we_general"/> for information
on auto-login and associating characters with a World). The list shown
is the list of all characters defined for that World. Select the entry
corresponding to the character you want to use to auto-login with that
character. If you select the main entry, the first character will be
used.</para>

<para>To connect directly, fill in the <guilabel>Host</guilabel> and
<guilabel>Port</guilabel> fields and click
<guibutton>Connect</guibutton>.</para>

<para>You can be connected to several Worlds simultaneously. To do
that, select the option
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Open</guimenuitem>
</menuchoice> from the menu. The World Selector dialog will be opened,
and you can select another World.</para>

</sect1>


<sect1 id="sec:interacting"><title>Interacting with the MUD</title>

<para>The figure below shows a typical KildClient session:</para>

<figure><title>A typical KildClient session with two open Worlds</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/typical.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>A typical KildClient session with two open Worlds.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The first thing to note is that, just like in other MUD clients,
there is an area where the output of the MUD is shown, and a text box
below where you can enter commands. You can edit the commands before
being sent, and only after you press <keysym>ENTER</keysym> the line
will be sent to the MUD.</para>

<para>The box that shows the output of the MUD keeps by default the
last 2000 lines received (but this number can be changed, see <xref
linkend="sec:we_misc"/>). You can recall the previous lines with the
scrollbar or with the <keysym>page up</keysym> and <keysym>page
down</keysym> keys.</para>

<para>A feature not so universal is the support for opening several
Worlds simultaneously, and using tabs to alternate between them. You
just need to click the tab to change to that World. If the name is
displayed in red, that means that there is new text in that MUD, text
you haven't seen yet. If the KildClient windows does not have focus
(that is, when you using another window and leave KildClient in the
background) and new text arrives in any World, the title of the
KildClient window will change to "(*) KildClient" to alert you of
that.</para>

<para>There are other ways to move to another open World. The keyboard
shortcuts <keysym>CTRL+Page up</keysym> and <keysym>CTRL+Page
down</keysym> move to the next or previous World, respectively.
Alternatively, you can use <keysym>ALT+Right arrow</keysym> o
<keysym>ALT+Left arrow</keysym> instead to achieve the same effect. To
got directly to a World, press <keysym>ALT+num</keysym>, where
<keysym>num</keysym> is a number from 1 to 9. This way you can move to
any one of the first nine open Worlds.</para>

<para>On the left of the command entry box there is a button with a
broom. Click on it to erase the whole command line.</para>

<para>You can recall recently typed commands with the arrow keys.
Pressing the <keysym>up arrow</keysym> recalls the previous command,
and the <keysym>down arrow</keysym> moves to the following
command. If the input box has multiple lines, as described below, then
use <keysym>Alt</keysym> and the arrows.</para>

<para>On the right, there is a button with an arrow poiting downwards.
Click on it to get a list of the last typed commands. Selecting one of
these commands will put it in the text box for you to repeat it,
possibly changing it before.</para>

<para>On the extreme right, there are two small arrows. These arrows
allow you to enlarge the input box if you type long input lines. The
input box can have from one to ten lines. The arrow pointing up
increases the size, the arrow pointing down decreases it.</para>

<para>The behaviour of input boxes with one or several lines is
different: if there is only one line, and more text than fits the
width is entered, the text is scrolled horizontally. On multi-line
input boxes, however, text that does not fit one line is wrapped to
the next line. A scroll-bar may be displayed if the whole text does
not fit in the number of lines selected.</para>

<para>As mentioned briefly before, the behaviour of the up and down
arrows is different. If the <keysym>Alt</keysym> key is held, then you
will retrieve other commands in the history. If you press just the up
and down arrows, it may retrieve another command or simply move the
cursor: if you have just sent a command or just retrieved a command,
then the arrow keys will move through other commands, but if you have
moved the cursor in order to edit, the up and down arrows will move to
the previous or next line. This may sound complicated, but is actually
natural, the arrows do what you expect them to do.</para>

<para>In the single-line input box (but not in the multi-line one), a
feature called <emphasis>command auto-completion</emphasis> is
enabled: when you start typing a command, a list of the previously
typed commands that start with the same string you've typed. You can
select one of them from the list to repeat it or change it.</para>

<para>However, in both input methods, you can type the start of a
command and press <keysym>Alt+Shift+Up arrow</keysym> to retrieve a
previous command that starts with the typed text. You can then use
<keysym>Alt+Shift+Up arrow</keysym> and <keysym>Alt+Shift+Down
arrow</keysym> to navigate through all the saved commands with that
prefix.</para>

<para>You can enter several commands at once in the command line
separating them with <literal>%;</literal>. For example, if you type
<literal>unlock door %; open door</literal>, two commands will be sent
to the MUD in sequence: first <literal>unlock door</literal>, and then
<literal>open door</literal>. Spaces around the <literal>%;</literal>
are ignore and can be used for clarity. Note: it is possible to
configure the command separator to be another string instead of
<literal>%;</literal>. See <xref linkend="sec:we_input"/>.</para>

<para>Another special feature of the command line is that you can
execute Perl statements from it. Starting a line with a slash
(<literal>/</literal>) causes that line not to be sent to the world,
but to be intepreted by the built-in Perl interpreter. To try it, type
in the command box <userinput>/$world-&gt;echonl("Hello, Perl
World!")</userinput>. You should see "<computeroutput>Hello, Perl
World!</computeroutput>" printed in the screen. What has happened is
that the command <userinput>$world-&gt;echonl("Hello, Perl
World!")</userinput> has been run by Perl, and this command causes a
string to be printed in the screen (but not to be sent to the MUD).
Don't worry if you do not understand the syntax yet, we will explain
it in <xref linkend="chap:perl"/>. For now, just keep in mind that if
you type a line starting with <literal>/</literal>, it will not be
sent to the MUD, but what follows the slash is treated as a Perl
command and executed.</para>

<para>Should you need to send a line that starts with
<literal>/</literal> to the MUD, use two slashes: entering
<userinput>//list</userinput> will send <userinput>/list</userinput>
to the MUD.</para>

<para>If you are using the multi-line input bar, you can enable to
built in spell checker to verify the text as you type. Misspelled
words will be highlighted with a red line below them, and you can
right-click on them to show a menu with possible spellings. To
configure this feature, see <xref linkend="sec:we_input"/>.</para>

</sect1>

<sect1 id="sec:closing_worlds">
<title>Closing Worlds and Exiting KildClient</title>

<para>When you are disconnected from a World (either because you
requested it, with the <literal>quit</literal> command or something
similar, or because the server has gone down), you will see a dialog
box from which you can choose from four options:
<guibutton>Reconnect</guibutton> will attempt to reconnect to the same
World (using the same character for auto-login, if there is more than
one defined, see <xref linkend="sec:we_general"/>). <guibutton>Connect
to another world</guibutton> will open the World Selection dialog (see
<xref linkend="sec:world-selector"/>) for you to choose another World
to connect to. <guilabel>Offline</guilabel> will keep the world open
so that you still see its output or execute some things with Perl.
Finally, <guibutton>Close</guibutton> will close the tab for that
World. If that was the only open World, KildClient will exit when you
press <guibutton>Close</guibutton>.</para>

<para>You can force disconnection from a World with the
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Disconnect</guimenuitem>
</menuchoice>
menu. Note that this is not the recommended way to leave a MUD, but it
might be necessary in other cases. The same dialog with the three
options will be shown.</para>

<para>If you choose
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Close</guimenuitem>
</menuchoice>
from the menu, the current World will be forcedly disconnected and
automatically closed (just as if you had selected
<guibutton>Close</guibutton> from the dialog). If this is the only
open World, KildClient will be exited.</para>

<para>To close all open Worlds and exit KildClient immediately, select
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Quit</guimenuitem>
</menuchoice>
from the menu.</para>

<para>These operations can also be run with Perl. To disconnect from a
World, use the <function>$world-&gt;dc</function> (that is, type
<userinput>/$world-&gt;dc</userinput> in the command box). To close the
World, use <function>$world-&gt;close</function>. And to quit KildClient
closing all Worlds, use <function>quit</function> (type
<userinput>/quit</userinput>, as you might imagine). The reason
<function>quit</function> does not have <literal>$world-&gt;</literal> in
front will be explained in <xref linkend="sec:perl_basics"/>, but for
now suffices to say that since it operates on all Worlds (and not in
one specific one), it does not have that.</para>

</sect1>


<sect1 id="sec:searching"><title>Searching Text</title>

<para>You can search the text saved in the buffer for occurrences of a
given word. To do that, use the
<menuchoice>
  <guimenu>Edit</guimenu>
  <guimenuitem>Find</guimenuitem>
</menuchoice>
menu.</para>

<para>When you select that menu, a bar appears above the command entry
box. Search is done through that bar. To start searching, type the
text you want to find in the entry box in the search bar. Searching in
KildClient is done <emphasis>incrementally</emphasis>, that is, as
soon as you type the first character, search starts (displaying the
first occurrence of that character). As you continue typing, searching
continues, always looking for occurrences of the text that you have
typed. If you are looking for a word, often you don't even need to
type the whole word, only the beginning is enough.</para>

<para>If you've found an occurrence of the text, but it is not the one
you intended, use the <guilabel>Find Next</guilabel> button beside the
entry box to find the next occurrence. (You can also use the
<menuchoice>
  <guimenu>Edit</guimenu>
  <guimenuitem>Find Next</guimenuitem>
</menuchoice>
menu.) Pressing the <keysym>Enter</keysym> key when in the input box
also activates the Find Next feature.</para>

<para>If the text you typed is not found, or if there are no more
occurrences of it when you press <guilabel>Find Next</guilabel>,
<guilabel>Not Found</guilabel> will be displayed in the search bar. In
this case, you can erase some characters and try again (if you made a
mistake), or reset the search and start again, as described
below.</para>

<para>To reset a search so that you can start again, either erase all
the text in the search box, or select
<menuchoice>
  <guimenu>Edit</guimenu>
  <guimenuitem>Find</guimenuitem>
</menuchoice>
from the menu again (which will also clear the entry box). When you do
that, searching will start again at the top of the buffer.</para>

<para>After you're done searching, click the small button with an
<guilabel>X</guilabel> in the left of the search bar to close the
search bar. You can also press <keysym>Esc</keysym> in the input
box.</para>

</sect1>

</chapter>



<chapter id="chap:world_editor"><title>Editing a World</title>

<para>This chapter will describe all the options found in the World
Editor that let you customize the behaviour of KildClient. Only
general options will be described here, some sections of the World
Editor, that allow you to configure features dealing with automation
(such as triggers, aliases, hooks, etc.) will be described in other
chapters, along with an explanation of that feature.</para>

<para>To access the World Editor for the currently open World, use the
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Edit</guimenuitem>
</menuchoice>
menu. It is also possible to edit Worlds from the World Selector
dialog, just click once in the World from the list and press
<guibutton>Edit</guibutton>.</para>

<para>There are several groups of options in that dialog. The
following sections will describe each one in turn.</para>


<sect1 id="sec:we_general"><title>General</title>

<para>The figure below shows the General section of the World
Editor:</para>

<figure><title>The General section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_general.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The General section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The first section, <guilabel>Connection</guilabel>, contains
parameters that specify how to connect to the MUD:</para>

<itemizedlist>
  <listitem><para><guilabel>Name</guilabel>: this specifies the name
  that will be shown in the World Selector, and also in the tab in the
  main window. It can be anything you want, that helps you identify
  the MUD.</para></listitem>

  <listitem><para><guilabel>Host</guilabel>: the host to connect to.
  It can be entered either as a name or as a numeric
  IP.</para></listitem>

  <listitem><para><guilabel>Port</guilabel>: the port to connect
  to.</para></listitem>

  <listitem><para><guilabel>Use SSL</guilabel>: if this is checked,
  the communication with the MUD will be encrypted and thus immune to
  casual eavesdropping. However, the MUD server must support this, if
  you try to connect using SSL to a server that does not understand
  it, the connection will fail.</para>

    <para>Note: you might not see this option. If it is not present,
    that means that you version of KildClient has been compiled
    without SSL support.</para>

    <para>Note: although the connection will be encrypted if the
    connection uses SSL, KildClient does not attempt any kind of
    certificate verification, so you must not assume that the
    connection is authenticated. You can, however, see some
    information on the certificate in the Statistics dialog (see
    <xref linkend="mnu:statistics"/>).</para>
  </listitem>
</itemizedlist>

<para>The second section, <guilabel>Auto-login</guilabel>, contains
the parameters that you need to configure if you want KildClient to
login automatically to the MUD for you. You can associate several
characters with a World, and then when you can select which character
you use to login to the MUD, as explained in <xref
linkend="sec:world-selector"/>.</para>

<para>First, select how the login will be made in <guilabel>Connection
Style</guilabel>. If this is set to "<guilabel>No
auto-login</guilabel>", no attempt will be made to login
automatically. This is the default.</para>

<para>There are two other options: "<guilabel>Diku</guilabel>", for
Diku-based mud servers, which prompt you for the character name and
then the password; and "<guilabel>lp</guilabel>" for lp-based mud
servers, in which you have to type <userinput>connect</userinput>
followed by the character name and password.</para>

<para>If neither of these options apply to your MUD, you should
disable auto-login here, but you can still use a hook to send commands
just after you connect. See <xref linkend="chap:hooks"/>.</para>

<para>Next follows a list of all the characters that you have defined.
Each character is associated with a password, however the password is
not displayed for security reasons.</para>

<para>To add a new character, press <guilabel>Add</guilabel> and enter
the character's name and password in the window that appears, then
press <guilabel>OK</guilabel>. The new character will be added to the
list. To edit an existing character, select it and press the
<guilabel>Edit</guilabel> button. To remove a character information,
select it and press <guilabel>Delete</guilabel>. Finally, to control
the order that the characters are displayed, use the
<guilabel>Up</guilabel> and <guilabel>Down</guilabel> buttons. Note
that the first character is considered the default and is the one used
if you connect using the main entry for that World.</para>

</sect1>


<sect1><title>Display settings</title>

<para>The Display category controls several aspects of the appearance
of KildClient. It is divided in sub-categories, which will be
described in the following sections.</para>


<sect2 id="sec:we_mainwindow"><title>Main Window</title>

<para>The figure below shows the Main Window section of the World
Editor:</para>

<figure><title>The Main Window section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_mainwindow.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Main Window section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>This section allows you to configure the main window where the
MUD text is shown.</para>

<para>You can set the font that is used for the text that is sent by
the MUD. Click on the button with the name of the font to pop-up a
dialog from where you can select another font. The change in the font
is applied immediately when a new font is selected.</para>

<para>Still with regard to fonds, another option that can be
configured in this section is whether to use bold fonts or not to
represent text that has the "bold" or "highlight" attribute set. By
default, this text is rendered in a lighter color and with a boldface,
but you can disable the use of a bold font from this dialog. You can
also change the colors used for the highlighted text, see <xref
linkend="sec:we_colors"/>.</para>

<para>You can also configure whether to use word wrap or not. If this
option is not set, lines will be broken when they do not fit the
window, even in the middle of a word. When this option is set, lines
will be wrapped between words, so that a word is not broken.</para>

</sect2>


<sect2 id="sec:we_colors"><title>Colors</title>

<para>The figure below shows the Colors section of the World
Editor:</para>

<figure><title>The Colors section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_colors.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Colors section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In this section you can configure the colors that will be used
by KildClient. The ANSI standard defines eight colors, both in the
"normal" state and in the "bold" state. These "bold" colors are by
default shown with lighter colors, and, optionally, with a bold font
also (see <xref linkend="sec:we_mainwindow"/>). Additionally, there are
"default" colors for the foreground and background, when no specific
color is set.</para>

<para>You can tweak the colors so that they look better in your
screen, or redefine them completely. To do that, click in the button
with the color, and a dialog will be shown for you to change the
color. The changes are applied immediately when a new color is
chosen.</para>

<para>Should you want to revert all colors to their built-in preset
values, use the <guibutton>Revert to default colors</guibutton>
button.</para>

</sect2>


<sect2 id="sec:we_statusbar"><title>Status Bar</title>

<para>The figure below shows the Status Bar section of the World
Editor:</para>

<figure><title>The Status Bar section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_statusbar.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Status Bar section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The first section allows you to change the font used in the
status bar. Click the button and a dialog will appear for you to
select the font.</para>

<para>The second section controls the display of some time counter
that appear in the right of the status bar. You can display the
total time connected to this world and/or the idle time, that is, the
time elapsed since you last sent a command to the MUD.</para>

<para>For each time, there are three options. <guilabel>Do not
display</guilabel> causes that time not to be displayed.
<guilabel>Display as hours, minutes and seconds</guilabel> displays
the time as something like 2h45m30s, while <guilabel>Display as
seconds</guilabel> would display that previous time as 9930s.</para>

<para>The behavior of the idle time counter can also be configured
with the <guilabel>Only reset idle time counter when a command is
entered</guilabel> checkbox. When the checkbox is unchecked (which is
the default), that time is reset whenever a command is sent to the
world, no matter if this command was typed, if it ran because of a
trigger, a timer, etc. When checked, the timer will only be reset when
you enter something in the command entry box and press
<keysym>ENTER</keysym>. Automatically sent commands will not cause the
counter to be reset.</para>

</sect2>

</sect1>


<sect1 id="sec:we_input"><title>Input</title>

<para>The figure below shows the Input section of the World
Editor:</para>

<figure><title>The Input section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_input.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Input section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The first section, <guilabel>Command Entry</guilabel>, controls
the behaviour of the command entry textbox:</para>

<itemizedlist>
  <listitem><para><guilabel>Keep last typed command in command entry
  box</guilabel>, causes the entry box not to be cleared when you
  press <keysym>ENTER</keysym>. The command you have just sent will be
  kept and can be repeated just by pressing <keysym>ENTER</keysym>
  again. It will be selected, so you can start typing another command
  to erase it.</para></listitem>

  <listitem><para><guilabel>Echo sent commands in terminal
  window</guilabel> controls whether the commands that are sent to the
  MUD are also echoed to the MUD window.</para></listitem>

  <listitem><para><guilabel>Number of commands to save in
  history</guilabel> specifies the number of commands that are saved
  and can be recalled with the arrow keys, with the button to the
  right of the entry box, or with command completion. If this is set
  to too high a number, KildClient will consume more
  memory.</para></listitem>

  <listitem><para><guilabel>Command separator</guilabel> allows you to
  configure the token used to separate commands. By default it is
  <literal>%;</literal>.</para></listitem>

  <listitem><para><guilabel>Use single-line input bar</guilabel> and
  <guilabel>Use multi-line input bar</guilabel> define the size of the
  input bar. If set to single-line, it will have only one line, and if
  you type more text than fits the width, the text will scroll
  horizontally. If, however, you select a multi-line input bar, the
  bar will have two or more lines, and text will wrap and be displayed
  in the next line. (Scroll-bars may be displayed if there is more
  text than fits.)</para>

  <para>If set to multi-line, you can specify how many lines to
  reserve for the input bar, from two to ten.</para></listitem>

  <listitem><para><guilabel>Enable auto-completion</guilabel> controls
  whether the auto-completion feature (see <xref
  linkend="sec:interacting"/>) is enabled or not. However,
  auto-completion only works for single line input
  bars.</para></listitem>

  <listitem><para>When auto-completion is enabled, you can specify
  after how many characters have been typed it will be activated. Just
  enter the number in the text box <guilabel>Activate auto-completion
  only after X characters have been
  entered</guilabel>.</para></listitem>

  <listitem><para><guilabel>Spell check typed text</guilabel>, if
  checked, enables the built-in spell checker. This spell checker
  works only with the multi-line input bar. If it is active,
  misspelled words are highlighted with a red line below them.
  Right-clicking on them pops up a menu with spelling
  suggestions.</para>

  <para>By default, the language used for spell checking is based on
  your current locale. If you want to set a specific language, enter
  its language code (as recognized by the aspell backend) in the
  box.</para>

  <para>Note that for spelling to work you need the gtkspell library.
  Your version might have been compiled without spelling
  support.</para></listitem>
</itemizedlist>

<para>The <guilabel>Font</guilabel> section allows you to configure
the font that is used in the command entry box. Click the button and a
dialog will appear for you to select the font.</para>

<para>The <guilabel>Flood Prevention</guilabel> feature is also
configured in this section. This feature is useful in MUDs that
disconnect you if you type 20 equal commands in a row, or something
like that. When you enable this feature, KildClient will count the
number of repeated commands you send. When you try to send the same
command for the 20th time, KildClient will send another command you
specify before, thus breaking the chain of repeated commands.</para>

<para>To use this feature, make enable the check box <guilabel>Do not
allow the same command to be sent X times in a row</guilabel>. Change
X for the number of equal commands that will disconnect you.</para>

<para>The <guilabel>Send this command</guilabel> textbox specifies
the command that will be sent to prevent too many equal commands to be
seen by the MUD. It should be set to a harmless command, because it
might be sent anytime.</para>

</sect1>


<sect1 id="sec:we_automation"><title>Automation</title>

<para>This section allows you to configure the features that make your
MUD playing experience easier, faster and more efficient. You can
define triggers, aliases, hooks, etc. here. These sections of the
World Editor will be described elsewhere, along with a description of
the features. Here we will deal with another section that is more
generic.</para>


<sect2 id="sec:we_scripting"><title>Scripting</title>

<para>The figure below shows the Scripting section of the World
Editor:</para>

<figure><title>The Scripting section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_scripting.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Scripting section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>There is only one parameter to be configured in this section:
<guilabel>Perl file to load</guilabel>. It allows you to specify a
file that will be read by the Perl interpreter when the World is
loaded. This file can contain sub-routine definitions that will be
available for you to use in your triggers, aliases etc., or to be
called directly. For more details, see <xref
linkend="sec:perl_basics"/>.</para>

<para>Enter the path to the file in the textbox, or click the button
next to it to open a dialog from which you can select a file.</para>

</sect2>

</sect1>


<sect1 id="sec:we_protocols"><title>Protocols</title>

<para>The figure below shows the Protocols section of the World
Editor:</para>

<figure><title>The Protocols section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_protocols.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Protocols section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>Here you can configure how KildClient uses some protocols to
enhance the player's experience while playing the MUD. Currenly you
can configure how KildClient behaves with regard to the MCCP protocol,
which compresses data sent by the MUD so that less data needs to be
sent.</para>

<para>By default, KildClient will use this protocol if the server
proposes it, but only if this proposal comes in at most one minute
after the connection has been established. This is done in order to
prevent bad players from trying to crash your client by sending the
special sequence that enables compression. Note, however, that
well-written servers prevent the user from sending such sequences to
other users. However, as compression is generally negotiated just
after connecting, leaving this option in its default state,
<guilabel>Enable if server proposes after connecting</guilabel> is
recommended.</para>

<para>If <guilabel>Enable if server proposes at any time</guilabel> is
selected, MCCP will be started whenever the start sequence is
received, no matter at what time.</para>

<para>Finally, you can disable MCCP altogether by selecting
<guilabel>Disable</guilabel>. This way sequences asking for
compression will be ignored, and the server will never send compressed
data. Attempts by malicious players will not succeed.</para>

</sect1>


<sect1 id="sec:we_misc"><title>Miscellaneous</title>

<para>The figure below shows the Miscellaneous section of the World
Editor:</para>

<figure><title>The Miscellaneous section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_misc.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Miscellaneous section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>There is only one category, <guilabel>Scrolling</guilabel>,
which controls the behavious of the scrollback buffer.</para>

<itemizedlist>
  <listitem><para><guilabel>Scroll on output</guilabel>, when checked,
  will cause the buffer to always scroll the end when new text is
  received, thus displaying it immediately. If not checked, the buffer
  is only scrolled if you are at the end.</para></listitem>

  <listitem><para><guilabel>Lines to save in scrollback
  buffer</guilabel> determines how many lines of output will be saved
  in the buffer for you to see again. Note that KildClient will get
  slower and will consume more memory if you set this to too high a
  number.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="sec:we_advanced"><title>Advanced</title>

<para>The figure below shows the Advanced section of the World
Editor:</para>

<figure><title>The Advanced section of the World Editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_advanced.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Advanced section of the World Editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In most cases, you will not need to change any of the settings
of this section.</para>

<para>The <guilabel>File</guilabel> text box specifies the file where
the World is saved. It is not necessary to enter anything here, a file
name will be generated automatically if you leave it blank. If you
enter a file name, it will override the default name. This means that
you can create a copy of a World by editing it, giving a new file
name, and then saving.</para>

<para>Note, however, that for the World to be recognized and listed in
the World Selector, it must have the <filename
class="extension">.wrl</filename> extension, and must be in the
directory where KildClient stores its files (<filename
class="directory">~/.kildclient</filename> under Linux and other
UNIX-like systems).</para>

<para>Another thing that can be configured in this section is the
character set used by KildClient. If you do not know what is that,
then simply ignore it and do not change anything. If you do know, just
select the character set that is used by the MUD from the combo box.
However, keep in mind that internally KildClient works with the UTF-8
character set. The only things that are changed by the selection you
can make in this section are what is output by the MUD and what is
sent to the MUD.</para>

<para>Finally, you can configure some aspects of the editors for
triggers, aliases, macros, timers and hooks (all displayed in the
World Editor).</para>

<para>You disable the confirmation dialogs that appear when you try to
delete a trigger, alias, macro, etc. from one of the graphical
editors. If you disable the <guilabel>Ask for confirmation before
deleting triggers, aliases, etc.</guilabel> there will not be a
confirmation dialog and the item will be deleted immediately. Be
warned that if this is unchecked and some item is deleted, you will
need to create it again if you delete it by mistake.</para>

<para>You can also show triggers and other objects defined by plugins
that are currently loaded. By default they are not shown, but you can
change this cheking the <guilabel>Show items defined by
plugins</guilabel> checkbox.</para>

<para>Note, however, that while having that option checked will allow
you to edit, delete and reorder the items defined by plugins, these
changes <emphasis>will not</emphasis> be made in the plugin file, and
the next time the plugin is loaded, the items will be as they were
before. You can use the editors to make changes and tests, but you
will need to alter the plugin file afterwards.</para>

</sect1>

</chapter>



<chapter id="chap:preferences"><title>Configuring KildClient</title>

<para>The previous Chapter described how to configure a World. Those
settings are individual for each World. There are some settings,
however, that apply to KildClient as a whole, which will be described
in this Chapter.</para>

<para>To access those settings, use the
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Preferences</guimenuitem>
</menuchoice>
menu. The following sections will describe the groups in the
Preferences dialog.</para>


<sect1><title>Appearance</title>

<para>The figure below shows the Appearance section of the Preferences
dialog:</para>

<figure><title>The Appearance section of the Preferences dialog</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/pref_appearance.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Appearance section of the Preferences dialog.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In this section you configure the colors that KildClient uses
for its own purposes. (The configuration of the colors that the MUD
displays is explained in <xref linkend="sec:we_colors"/>.)</para>

<para>Two colors can be configured: <guilabel>Informative
messages</guilabel> is the color used by KildClient to print messages
about the status of the connection, such as the ones showing that a
connection is being tried or has succeeded. <guilabel>Command
echo</guilabel> specifies the color in which the commands you send to
the World are printed in the screen (if this feature is enabled, see
<xref linkend="sec:we_misc"/>).</para>

<para>In each case, select from the drop-down list the color you want.
Note that the actual color that is displayed depends on how it was
configured in the World Editor (see <xref
linkend="sec:we_colors"/>).</para>

<para>Another thing to be configured here is the position where the
tabs representing the open Worlds are displayed. They can be at the
top, bottom, left or right. Select the one you want from the combo
box.</para>

<para>Finally, you can enable or disable the <guilabel>Flash window
when new text is received</guilabel> feature. When it is enabled, if
text is received in the mud while you are at another window,
KildClient's window will flash to draw your attention. If disabled,
you can still know that new text has been received because the
titlebar will have a <literal>(*)</literal> prepended. Note, however,
that the exact behaviour of this feature might depend on your Window
Manager, and that some window managers do not do anything for windows
with the "Urgent" flag set.</para>

</sect1>


<sect1><title>Sending</title>

<para>The figure below shows the Sending section of the Preferences
dialog:</para>

<figure><title>The Sending section of the Preferences dialog</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/pref_sending.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Sending section of the Preferences dialog.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In this section you configure the default paramenters used when
sending several commands at once. This setting is used in the Command
History (<xref linkend="sec:cmd_history"/>) and Multi-line Send
(<xref linkend="sec:ml_send"/>) dialogs.</para>

<para>You specify the number of commands or lines that are sent
simultaneously, and the delay between sending each group of
commands/lines (containing the specified number of commands/lines,
naturally). Note, however, that the values you set here are only
defaults, you can change the values in the dialogs of those features
if you need so.</para>

</sect1>


<sect1 id="pref:progs"><title>External Programs (Linux)</title>

<para>This section of the Preferences dialog only appears when
KildClient is run in Linux.</para>

<para>The figure below shows the External Programs section of the
Preferences dialog:</para>

<figure><title>The External Programs section of the Preferences
  dialog</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/pref_progs.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The External Programs section of the Preferences
      dialog.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In this section you can configure the command that will be run
when you right-click in a URL that appears in the MUD window and
select <guilabel>Open Link</guilabel>. The command will be executed,
with <literal>%s</literal> replaced with the URL's address. The
ampersand (<literal>&amp;</literal>) in the end means that the command
is to be executed in the background, so that you can continue using
KildClient while browsing the URL.</para>

<para>You can also set a command used to play audio files (see <xref
linkend="sec:sounds"/>). Enter the command, with <literal>%s</literal>
in the place of the file path. The default should work (it uses the
SOX program, which is usually installed), but you can use other
commands if you use ALSA, ARTS, ESD, JACK, etc.</para>

</sect1>

</chapter>



<chapter><title>Menu Reference</title>

<para>This chapter will describe all the menus and their commands in
KildClient.</para>


<sect1><title>World menu</title>

<sect2><title>Open</title>

<para>This menu command opens the World Selector dialog for you to
connect to a World, either a saved one or a new one. You can also edit
the saved worlds from the World Selector dialog.</para>

<para>See <xref linkend="sec:world-selector"/> for more information
on opening Worlds.</para>

</sect2>

<sect2><title>Reconnect</title>

<para>If you are not connected to a World, but have it still open (in
offline mode), use this menu to connect again to the World. If you are
connected, this command closes the current connection and reopens
it.</para>

</sect2>

<sect2><title>Disconnect</title>

<para>This command closes the connection to the World. Note that this
is not the recommended way to exit from a MUD, you should use the
proper command (generally <userinput>quit</userinput>).</para>

</sect2>

<sect2><title>Connect to Another</title>

<para>This command opens the World Selector (see <xref
linkend="sec:world-selector"/>) for you to connect to another World
using the same tab. If you are still connected to a World, the
connection will be closed.</para>

</sect2>

<sect2><title>Close</title>

<para>This command closes the connection to the World (if it is open)
and closes the current tab. If this is the only tab, the program is
exited.</para>

</sect2>

<sect2><title>Edit</title>

<para>This command brings up the World Editor for you to configure the
World. See <xref linkend="chap:world_editor"/>.</para>

</sect2>

<sect2><title>Save</title>

<para>This command saves any changes made to the World to the disk so
that they are made permanent. Note that whenever a World is closed, it
is automatically saved before.</para>

</sect2>

<sect2 id="mnu:statistics"><title>Statistics</title>

<para>This command opens a dialog showing some information and
statistics about the currently open World. If the version you are
running supports SSL and you are connected using SSL (see <xref
linkend="sec:we_general"/>), some information about the SSL session
and the certificate are displayed.</para>

</sect2>

<sect2><title>Previous and Next</title>

<para>These two commands allow you to navigate between the open
Worlds, going to the next or previous tabs, repectively.</para>

</sect2>

<sect2><title>Quit</title>

<para>This command exits KildClient, closing any open Worlds. If an
open world has "OnCloseConnected" hooks (see <xref
linkend="chap:hooks"/>), they are executed. If there is at least one
open world without such hook, you are asked for confirmation
first.</para>

</sect2>

</sect1>


<sect1><title>Edit Menu</title>

<sect2><title>Cut</title>

<para>This command copies the text selected in the command entry box
to the clipboard and deletes the selected text.</para>

</sect2>

<sect2><title>Copy</title>

<para>This command copies text either from the MUD (that is, in the
output window) or from the command entry box to the clipboard.</para>

<para>If there is text selected in the main window, than this text is
copied. Otherwise, if there is text selected in the command entry box,
it is this text that is copied.</para>

</sect2>

<sect2><title>Paste</title>

<para>This command pastes the text in the clipboard to the command
entry box, possibly overwriting any selected text.</para>

</sect2>

<sect2><title>Delete</title>

<para>This command deletes the text selected in the command entry
box.</para>

</sect2>

<sect2><title>Find and Find Next</title>

<para>These commands are used to search for some text in the output
buffer. Their use is described in <xref linkend="sec:searching"/>.</para>

</sect2>

</sect1>



<sect1><title>Input Menu</title>

<sect2><title>Clear</title>

<para>This command clears the command entry box. The same can be
achieved by using the button to the left of the command entry
box.</para>

</sect2>

<sect2><title>Previous and Next</title>

<para>These commands retrieve the previous or next command in the
history, putting them in the command input box. They are equivalent of
pressing <keysym>Alt+Up</keysym> or <keysym>Alt+Down</keysym> (or just
the arrows, in some circunstances).</para>

</sect2>

<sect2><title>Find Previous and Find Next</title>

<para>These commands search the command history for a command that
starts with the text that is in the input bar. To use that feature,
enter the first characters of the command you want to retrieve and
select Find Previous. You can navigate through other commands starting
with that prefix with these menu entries.</para>

</sect2>

<sect2 id="sec:cmd_history"><title>Command History</title>

<para>This command allows you to review the commands that have been
sent recently, and send one or more commands again. When you select
the menu item, a dialog like this appears:</para>

<figure><title>Command History Dialog</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/cmdhistory.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Command History Dialog.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The list on the left shows the commands which are saved. You can
configure how many commands are saved, see <xref
linkend="sec:we_input"/>.</para>

<para>To send again commands to the World, select the commands you
would like to send and press <guilabel>Send</guilabel>. Since most
MUDs cannot handle too much user input at once and disconnect you in
this case, you can add a delay after each sent command, so that the
commands are not sent all at once, but with pauses. You can specify
the delay and also how many commands are sent at one time. The delay
is added after each group of sent commands.</para>

<para>You can also press <guilabel>Send &amp; Close</guilabel> to send
the selected commands and close the dialog afterwards.</para>

<para>You can also put a command in the command entry box to edit it.
To do so, select a command (in this case you must select only one) and
press <guilabel>Recall</guilabel>. If you press <guilabel>Recall &amp;
Close</guilabel> instead, the command is recalled and the dialog is
closed.</para>

<para>To search for commands containing a given string, used the
<guilabel>Find</guilabel> and <guilabel>Find Next</guilabel> buttons.
Use the former one to start a search, and the later to find more
commands with the string. To start another search, use
<guilabel>Find</guilabel> again.</para>

</sect2>

<sect2 id="sec:ml_send"><title>Multi-line Send</title>

<para>This command allows you to send several lines of output and/or a
file to the World. When you select the menu item, a dialog like this
appears:</para>

<figure><title>Multi-Line Send</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/mlsend.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Multi-Line Send Dialog.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>You can send a file to the World, and you can also send text
before and after the file if you need. Naturally, you can also send
only some text without sending a file. Just leave the fields you don't
need blank.</para>

<para>It is also possible to prefix all the lines with a string (such
as <literal>chat</literal>), or to add a string to the end of all
lines. If you want that, fill in the appropriate fields, if not, just
leave them blank.</para>

<para>Most MUDs cannot handle too much user input at once and
disconnect you in this case. To avoid that, you can add a delay after
each sent lines, so that the text is not sent all at once, but with
pauses. You can specify the delay and also how many lines are sent at
one time. The delay is added after each group of sent lines.</para>

<para>If you select "Keep dialog open after sending", the dialog will
not be closed after the text starts to be sent, so you can make
further changes to the text.</para>


</sect2>

<sect2><title>Test Triggers</title>

<para>This command brings up the Test Triggers window, which is
described in <xref linkend="sec:test_triggers"/>.

</para>

</sect2>

</sect1>


<sect1><title>Preferences Menu</title>

<sect2><title>Disable Triggers, Aliases, Macros or Timers</title>

<para>If each of these menu entries is checked, then the corresponding
automation feature is disabled: lines are not matched against
triggers, aliases do not replace typed commands, macros and timers do
not run. Use them if you want to temporarily disable all of them,
since the triggers, aliases, macros or timers are not deleted.</para>

</sect2>

<sect2><title>Debug Matches</title>

<para>If this entry is selected, whenever a trigger or alias matches,
information is printed about it. The information is printed on stdout,
which means you must start KildClient from a terminal.</para>

</sect2>

<sect2><title>Preferences</title>

<para>This command opens a dialog where you can configure some aspects
of KildClient global to all Worlds. See <xref
linkend="chap:preferences"/>.</para>

</sect2>

<sect2><title>Edit Default World</title>

<para>This command opens a dialog where you can set some default
parameters used for Worlds. For example, you can define your preferred
font or colors, and all new Worlds will use these default font and
colors.</para>

<para>The things that can be set are described in <xref
linkend="chap:world_editor"/>, but not all things described there can
be set as default parameters. (There's no sense in having a default
World name, for example.)</para>

</sect2>

</sect1>


<sect1><title>Help Menu</title>

<sect2><title>Help</title>

<para>This commands opens a browser showing the KildClient manual
(which you are reading now).</para>

</sect2>

<sect2><title>About</title>

<para>This commands shows a window with some information about the
program.</para>

</sect2>

</sect1>

</chapter>



<chapter id="chap:perl"><title>Using Perl in KildClient</title>

<para>This chapter will describe briefly how to use Perl (Practical
Extration and Report Language, or, according to some, Pathologically
Eclectic Rubbish Lister) in KildClient. Even though it will give a few
examples of things that would certainly be known already by people who
know Perl, this Chapter is not meant to be a Perl tutorial. If you
want to learn Perl from the start, you should read its man pages, find
a tutorial or a good book on the subject (there are plenty of these).
Some knowledge of Perl will certainly help in understanding this
Chapter.</para>


<sect1 id="sec:perl_basics"><title>The Basics</title>

<para>KildClient has a built-in Perl interpreter. To run a perl
statement, just type if preceded by a slash (<literal>/</literal>) in
the command entry box. The statement will be executed by the Perl
interpreter instead of being sent to the MUD.</para>

<para>The statement can be anything that Perl will accept. You can
actually execute several Perl statements if you separate them with
<literal>;</literal> (no need to add <literal>/</literal> again, just
once in the beginning of the line). You can call sub-routines, execute
conditional or loop constructions, call a built-in function, do
variable assignments, or even define a sub-routine. However, the
statement must be complete. You cannot enter something like
<userinput>/$myVar =</userinput> and then enter
<userinput>/"some_value";</userinput>, the statement must be complete
in one line. Technically, each line you enter is executed inside an
<function>eval</function> block, so anything you want executed must be
valid code inside an <function>eval</function> block.</para>

<para>All built-in Perl functions are accessible for you to use, and
you can load Perl modules and use their functionality. However, that
is not enough, because Perl's built-in functions will not allow you to
interact with the World. Because of that, KildClient defines a set of
functions that you can use to interact with the World. A full list
describing them detailedly is found in <xref
linkend="app:functions"/>, but some of the most useful ones will be
described in this Chapter. Many of these functions deal with creating
and editing triggers, gags, aliases etc. These will be described in
the corresponding chapters.</para>

<para>It is possible to get help on all functions using the
<function>help</function> function. It takes as argument the name of
the function. Note that since <function>help</function> is nothing
else than another Perl function, the name of the function for which
you want help is just an argument to it, and must be passed as a
string. That is, to get help on the <function>echo</function>
function, type <userinput>/help "echo"</userinput>. (Naturally, you
can enclose <parameter>"echo"</parameter> in parenthesis, but this is
not necessary.)</para>

<para>Some functions are in a way global, that is, they do not refer
to a specific world. One such example is <function>colorize</function>
(see <xref linkend="func:colorize" endterm="func:colorize.title"/>),
which inserts ANSI color codes in strings (useful when you want to
print something in the screen). These are called like any built-in
Perl function. For example, if you enter <userinput>/$colorstr =
colorize("&amp;WI'm in white!")</userinput>, the variable
<varname>$colorstr</varname> will hold a string that would be printed
in white.</para>

<para>Many functions, however, are specific to a World, such as
<function>echo</function> (see <xref linkend="func:echo"
endterm="func:echo.title"/>), which prints something in the World
window (but does not send it to the World). Because of that, they are
called in a slightly different way. To print that string which has
just been created, you would enter
<userinput>/$world-&gt;echo($colorstr)</userinput>. Those that know
Perl will recognized this as a method call of the
<varname>$world</varname> instance. Indeed, <varname>$world</varname>
is an instance of the class <classname>World</classname> class. This
class defines several functions that allow interaction with a World.
On start-up, the <varname>$world</varname> variable is created and
references the current World.</para>

<para>It is also possible to control other worlds, if you have a
variable pointing at them. You can get such a variable with the
<function>getworld</function> function (see <xref
linkend="func:getworld" endterm="func:getworld.title"/>). In that
case, you should use the variable you got instead of
<varname>$world</varname>.</para>

<para>If all the above did not make sense to you, do not worry. Just
remember that many functions have to be called by adding
<literal>$world-&gt;</literal> to the front. These functions will always
be listed with that in front.</para>

<para>When a World is opened, the Perl interpreter reads and executes
a file you specify. (See <xref linkend="sec:we_scripting"/> for
information on how to specify the file.) In this file, you can define
sub-routines and variables. They will be then available for you to use
during your session. If you define a sub-routine called
<function>sendGreetings</function>, you can type
<userinput>/sendGreetings</userinput> and the sub-routine will be
executed. Or, if you define a variable, you can use it
anywhere.</para>

<para>It should be noted that each World has its own Perl interpreter,
with its functions and variables. What you do in one World does not
affect the others.</para>

</sect1>


<sect1><title>Echoing and Sending Text</title>

<para>As mentioned in the previous section, the
<function>$world-&gt;echo</function> function is used to print (or
<emphasis>echo</emphasis>) text to the MUD window, without sending it
to the World. It works like the <function>print</function> built-in
function: it accepts any number of arguments, and echoes all of them,
sequentially.</para>

<para>For example, <userinput>$world-&gt;echo("Variable var contains ",
$var, ".\n")</userinput> would print the first string, followed by the
contents of <varname>$var</varname>, followed by a period and a new
line. Of course, you could do all that in a single string using
variable interpolation.</para>

<para>A variant of <function>$world-&gt;echo</function> is
<function>$world-&gt;echonl</function>. The difference is that
<function>$world-&gt;echonl</function> always prints automatically a
newline after each argument. This is just a shorthand to make some
things simpler and possibly more readable.</para>

<para>Similar to <function>$world-&gt;echo</function> is the
<function>$world-&gt;send</function> function. This function sends
something to the MUD. For example,
<userinput>$world-&gt;send("who")</userinput> will have the same effect
as if you had typed <userinput>who</userinput> in the command entry
box and pressed <keysym>ENTER</keysym>. Note that you do not have to
add a newline to the end of the line to send, because
<function>send</function> automatically sends a newline after each
argument (since commands must be terminated by a newline for the MUD
to recognize them).</para>

<para>It is possible to pass several arguments to
<function>send</function>. If you do so, each argument will be sent as
a separate command. For example, <userinput>$world-&gt;send("who",
"look")</userinput> will first send a <literal>who</literal> to the
MUD, and then a <literal>look</literal>, just as if you had typed each
of these commands in order.</para>

<para>All the examples given above did nothing that could not be done
without Perl, and using <function>send</function> for that was
actually less efficient that typing the commands directly. However,
when combined with variables and/or control flow structures,
<function>send</function> can actually be quite useful.</para>

<sect2 id="sec:paths"><title>Paths and Speed-Walking</title>

<para>A useful feature of some MUD clients, which KildClient
implements, is the support for <emphasis>speed-walking</emphasis>.
This feature allows you to define paths to go directly from one place
to another without having to type a lot of movement commands.</para>

<para>For example, suppose that to go to some place from a fixed point
(such as the center of a town) you need to take the following
directions: <literal>s s s e e s e e e e n nw n</literal>. This is
often written in a more compact way as <literal>3s 2e s 4e n nw
n</literal>. KildClient allows you to send to the MUD all the 13
required commands in a single command. To do that, use the
<function>path</function> function. For example, if you enter
<userinput>/path("3s2es4en{nw}n")</userinput> in the command line, 13
commands will be sent to the MUD: exactly the 13 that form the path
defined above.</para>

<para>Note the syntax: the movement commands are defined one after
another, optionally prefixed by a number, which determines how many
times that command will be sent. So <literal>3s</literal> means send
<literal>s</literal> three times. If there is no number, the command
is sent only once.</para>

<para>Note also that the command to move to the north-west is enclosed
in braces: <literal>{nw}</literal>. This is because if the
<function>path</function> function sees <literal>nw</literal>, it will
think you want to move to the north than to the west. Enclosing it in
braces causes <function>path</function> to see that as a single
command. Should you need to move several times to the northwest, you
can add a number before: <literal>4{nw}</literal> will send
<literal>nw</literal> four times.</para>

<para>Naturally, you can include any command that is not a single
letter in braces to force <function>path</function> to see it as a
command. It is likely that some paths will need something like
<literal>{open door}</literal> in the middle.</para>

<para>Of course, simply entering paths in the command line is not that
useful. But you can store the path in a variable, and then just call
<userinput>path($stored_path)</userinput>. Just add a line that
defines the variable to you script file (see <xref
linkend="sec:perl_basics"/>), and you will be able to use the
variabled anywhere.</para>

<para>Alternatively, you can define an alias (see <xref
linkend="chap:aliases"/>) or a macro (see <xref
linkend="chap:macros"/>) to execute your path even faster. The
<literal>easypath</literal> plugin does that, see section <xref
linkend="plugin:easypath"/>.</para>

</sect2>

</sect1>


<sect1 id="sec:sounds"><title>Playing Sounds</title>

<para>To play a sound (for example, as the action of a trigger, to
call your attention), use the <function>play</function> function. Pass
it the path to the sound file, for example:
<userinput>/play("/home/joe/sounds/beep.wav")</userinput>.</para>

<para>Under Windows, this function supports playing WAV files. Under
Linux, you must set-up a command to play sounds, see <xref
linkend="pref:progs"/>.</para>

</sect1>


<sect1><title>Saving Variables Permanently</title>

<para>You can define variables for use in your Perl scripts. Since
KildClient has a full-featured Perl interpreter, you can use all kinds
of variables Perl supports (scalars, arrays, hashes, and even
references to build complex data structures), and you use them just
like you would in Perl.</para>

<para>However, when you close the World, the variables and their
values are lost. However, it is often desirable to keep the values of
variables across sessions, and KildClient has a mechanism for
that.</para>

<para>A variable can be made <emphasis>permanent</emphasis>. All
variables that are marked as permanent will be saved when you close
the World, and will be reloaded from the saved values when the World
is opened again later. This way, their values are saved across
sessions.</para>

<para>To make a variable permanent, open the World Editor (see <xref
linkend="chap:world_editor"/>) and select the
<guilabel>Variables</guilabel> section inside
<guilabel>Automation</guilabel>.</para>

<para>There you will see a list of the variables that are set to be
permanent:</para>

<figure><title>Permanent Variables</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_vars.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Permanent Variables.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>To add a variable, click the <guilabel>Add</guilabel> button. A
window will open for you to enter the name of the variable.</para>

<para>To make one or more variables temporary again, select them and
press <guilabel>Delete</guilabel>. They will be removed from the
list.</para>

<para>Finally, if you mispell the name of a variable, select it and
press <guilabel>Edit</guilabel> to correct it.</para>

<para>You can also change the order of the variables with the
<guilabel>Up</guilabel> and <guilabel>Down</guilabel> buttons. This is
usefor for grouping similar variables together, but does not otherwise
affect the saving of the variables.</para>


<sect2><title>Permanent Variables in the Command Line</title>

<para>It is possible to make a variable permanent from the command
line. To do that, use the <function>$world-&gt;makepermanent</function>
function, passing the name of the variable as the argument. Note that
since you must pass the name of the variable, you must use quotes, and
preferably single quotes so that the variable does not get
interpolated. For example, to make the variable
<varname>$kill_count</varname> permanent, run
<userinput>$world-&gt;makepermanent('$kill_count')</userinput>. Now when
you close the World, the value of <varname>$kill_count</varname> will
be saved, and when you reopen it later, the value will be
restored.</para>

<para>It is possible to make more than one variable permanent at one
time, just pass all their names as arguments to
<function>$world-&gt;makepermanent</function>.</para>

<para>If you want a variable to stop being permanent (that is, to
become <emphasis>temporary</emphasis> again), use the
<function>$world-&gt;maketemporary</function> function. It is called just
like <function>makepermanent</function>, and has the opposite
effect.</para>

<para>To get a list of the variables that are currently permanent, use
the function <function>$world-&gt;listpermanent</function>. This function
has no arguments, and prints all the names of the variables that are
permanent.</para>

</sect2>

</sect1>


<sect1><title>Controlling Worlds with Perl</title>

<para>In <xref linkend="sec:closing_worlds"/> it was explained that
you can disconnect from a World with the
<function>$world-&gt;dc</function> function. It now should be clear why
there is a <literal>$world-&gt;</literal> in front. Another function that
you know already is <function>$world-&gt;close</function>, to disconnect
and close a World.</para>

<para>There are a few more functions that allow you to control Worlds
from Perl. The <function>$world-&gt;next</function> and
<function>$world-&gt;prev</function> move to the next or previous world
in the list of tabs. It is also possible to pass an argument to them,
specifying how many Worlds to move. So,
<userinput>$world-&gt;next(2)</userinput> moves two Worlds forward, and
<userinput>$world-&gt;prev(3)</userinput> moves three Worlds back.</para>

<para>To go to a specific World, use the <function>gotow</function>
function (which <emphasis>does not</emphasis> belong to the
<classname>World</classname> class, since it does not depend on a
particular World), passing as argument a string with the name of the
World.</para>

<para>Finally, you can use the <function>quit</function> function to
disconnect and close all Worlds and then exit KildClient.</para>

</sect1>

</chapter>



<chapter id="chap:triggers"><title>Triggers</title>

<para>Triggers allow you to react automatically to text that comes
from the MUD. This reaction can be of two forms: sending something to
the MUD in reply, or there may be no direct interaction with the MUD,
but something might be printed in the screen, or something else done
to call your attention.</para>

<para>Sometimes the action of a trigger is to change the line that was
received and that activated the trigger. You might want to match all
lines that contain a certain word (such as your character's name) and
print these lines (or part of these lines) in a different color to
draw attention. And sometimes you might want to omit some lines, such
as everything said by some annoying player, or some messages that are
not relevant for you. This kind of trigger is often called a
<emphasis>gag</emphasis>. Both these features are supported by
KildClient.</para>

<para>Triggers are defined by specifying a
<emphasis>pattern</emphasis> against which all lines received from the
MUD are matched. If there is indeed a match, an
<emphasis>action</emphasis> specified by you is executed. If the
trigger is a <emphasis>gag</emphasis>, then the line that matched will
not be printed in the screen, otherwise it is printed normally. (Note
that printing actually happens before the action is executed, even if
here things were described in another order for ease of
understanding.)</para>

<para>The above description was very brief and was meant just to give
a basic idea of how triggers work. Next follows a more detailed
explanation of all aspects involving triggers.</para>


<sect1><title>Creating and Editing Triggers</title>

<para>The easiest way to create and alter triggers is from the World
Editor, the place where all settings of a World are altered (see <xref
linkend="chap:world_editor"/>).</para>

<para>Trigger are defined in the <guilabel>Triggers</guilabel> section
inside the <guilabel>Automation</guilabel> section. When you open that
section, you'll see a list of the defined triggers and some buttons
like this:</para>

<figure><title>The graphical Trigger editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_triggers.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The graphical Trigger editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The main part of the window is the list of defined triggers. The
columns are as follows:</para>

<itemizedlist>
  <listitem><para><guilabel>Enabled</guilabel> specifies whether the
  trigger is enabled or not. Triggers that are not enabled are not
  active and will not be tried when a line is received, but they
  remain in the list so that they can later be enabled
  again.</para></listitem>

  <listitem><para><guilabel>Name</guilabel> is a name that is assigned
  to a trigger. This helps you identify the trigger's purpose and is
  useful when editing a trigger via the command line (as described in
  <xref linkend="sec:edit_trigger_cmdline"/>). Assigning a name to a
  trigger is optional.</para></listitem>

  <listitem><para><guilabel>Pattern</guilabel> and
  <guilabel>Action</guilabel> are the parameters for the trigger, and
  they define the trigger's action, as described
  above.</para></listitem>

  <listitem><para><guilabel>I Case</guilabel> (for "Ignore Case"), if
  set, means the case is not considered while matching the pattern,
  that is, a case-insensitive match is done.</para></listitem>

  <listitem><para><guilabel>Gag</guilabel> defines if the line that
  matches the trigger will be printed. If this is active, the line is
  gaged (omitted) from the main screen.</para></listitem>

  <listitem><para><guilabel>Gag Log</guilabel> defines if the line
  that matches the trigger will be written to the log file. If this is
  active, the line is gaged (omitted) from the log file, if logging is
  enabled (see <xref linkend="chap:logging"/>.</para></listitem>

  <listitem><para><guilabel>Keep Exec</guilabel> defines what happens
  when the trigger is matched. By default, if a trigger matches
  further matching of that line against other triggers is stopped. If,
  however, this option is active and the trigger matches, the line
  continues being tried against other triggers.</para></listitem>

  <listitem><para><guilabel>Rewriter</guilabel> defines if the trigger
  is a <emphasis>rewriter</emphasis> trigger, a special kind of
  trigger described in <xref
  linkend="sec:trigger_rewriter"/>.</para></listitem>

  <listitem><para><guilabel>Plugin</guilabel>: if this is non-empty,
  it means that the trigger belongs to a plugin (and the name of the
  plugin is displayed). However, by default plugin triggers are not
  displayed. See <xref linkend="sec:we_advanced"/> for information on
  how to display plugin triggers here.</para></listitem>
</itemizedlist>


<sect2 id="sec:add_trigger_gui"><title>Adding Triggers</title>

<para>To add a new trigger, press the <guilabel>Add</guilabel> button.
This will open a window for you to edit the new trigger's parameters:</para>

<figure><title>The window to edit triggers</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_trigger_edit.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to edit triggers.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>What can be set represents the columns described above.</para>

<para>When you are finished, press <guilabel>OK</guilabel> and the
trigger will be added. If you change your mind, press
<guilabel>Cancel</guilabel> and the trigger will not be added.</para>

<para>To see some things triggers can do, read <xref
linkend="sec:trigger_cmdline"/>. If you want to try the triggers
described there, you can create them from the World Editor.</para>

</sect2>


<sect2><title>Altering Triggers</title>

<para>To edit a trigger, select it by clicking its line in the list
(the line will be highlighted), and press the
<guilabel>Edit</guilabel> button. A window like the one used for
adding trigger (see <xref linkend="sec:add_trigger_gui"/>) will be
opened, filled with the trigger's parameters. Change what you want,
and press the <guilabel>OK</guilabel> to commit the changes. If,
however, you change you mind, press <guilabel>Cancel</guilabel> and
the changes will be not be made, the trigger will remain as it was
before.</para>

<para>Another shorter way to edit a trigger is to double click its
line in the list.</para>

<para>It is also possible to change the value of the binary options
(those represented by a check box) directly from the trigger list.
Make sure that the trigger you want to change is selected, and click
in the check button. The state will be toggled.</para>

<para>To delete a trigger, select it and press the
<guilabel>Delete</guilabel> button. You will be asked for
confirmation, and can cancel the operation, but once deleted, you
cannot recover the trigger. If you want, you can disable this
confirmation dialog, but if you do so and click the
<guilabel>Delete</guilabel> button, the only way to undo your action
will be creating the trigger again. See <xref
linkend="sec:we_advanced"/>. To delete several triggers at once,
select them all and press <guilabel>Delete</guilabel>.</para>

<para>The final thing that needs to be explained with regard to
triggers is how to reorder them. Triggers as tried from the first one
to the last, so in a few cases the order might matter. To move a
trigger up or down in the list, select it and press the corresponding
button.</para>

</sect2>

</sect1>


<sect1 id="sec:trigger_highlight">
<title>Changing the Style of the Matched Text</title>

<para>It is possible to cause a trigger to change the style of the
line that matched (or of a part of it). This can be used, for example,
to make some text that interests you stand out.</para>

<para>To do that, enable the <guilabel>Change Style</guilabel> check
box in the Edit Trigger dialog (see <xref
linkend="sec:add_trigger_gui"/>). The <guilabel>Configure</guilabel>
button then allows you to set the style to be applied. When pressed,
it brings up a window like this:</para>

<figure><title>The window to configure style</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_trigger_highlight.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to configure the style to be applied.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>First you should select what is going to have the style changed.
The style can be applied to the whole line that matched against the
trigger, to the part of the line that matched the trigger pattern, or
the the part of the line that was captured by one of the parentheses
in the pattern (if they are used, naturally).</para>

<para>Next you can configure the style to be applied. You can change
the color of the text, and apply or remove italics, strike-thru and
underlining. In all these options, the default is "<guilabel>Do not
change</guilabel>", which means that the trigger does not affect the
style as sent by the MUD. If you select some option, then your
selection will override the style that the MUD sends.</para>

</sect1>


<sect1 id="sec:trigger_cmdline">
<title>Defining Triggers in the Command Line</title>

<para>For those more used to Perl and to command lines, it is also
possible to define and alter triggers from the command line. This is
done with a series of Perl function.</para>

<para>Triggers are defined with the
<function>$world-&gt;trigger</function> function. There are many ways to
use this function, and we will start describing them here.</para>

<para>The simples way to use that function is with two arguments:
<function>$world-&gt;trigger(<replaceable>pattern</replaceable>,
<replaceable>action</replaceable>)</function>. This defines a trigger
that will match against <replaceable>pattern</replaceable> and execute
<replaceable>action</replaceable> when a match happens.</para>

<para>What exactly is <replaceable>pattern</replaceable>? It is a
<emphasis>regular expression</emphasis>. If you know Perl, you
certainly know what is a regular expression. If not, it is advised
that you look for some more information on it, there are plenty of
tutorials on the Internet. For those who know them, you can use the
full power of Perl's regular expressions in triggers, because Perl is
used for the matching.</para>

<para>What about the <replaceable>action</replaceable>? It can be
anything that could be entered in the command line. If it is simply a
command, that command will be sent to the MUD. Or you can stack
several commands separating them with <literal>%;</literal> as
described in <xref linkend="sec:interacting"/>.</para>

<para>Here's an example of a very simple trigger:</para>

<example id="ex:simplest_trigger"><title>A very simple trigger</title>
<programlisting>
$world-&gt;trigger('has attacked you!', 'wield sword')
</programlisting>
</example>

<para>Whenever a line that contains the phrase "<literal>has attacked
you!</literal>" is received, the command "<userinput>wield
sword</userinput>" will be automatically be sent. Note that in this
case the received line will probably be something like "<literal>An
orc has attacked you!</literal>", but the trigger matches because that
line contains the <replaceable>pattern</replaceable>. This is a
feature of regular expressions. If you want to match the entire line
and not only part of it, you must use the <literal>^</literal> and
<literal>$</literal> anchors in the beginning and end,
respectively.</para>

<para>But the real power is the fact that you can also run Perl
commands in response to triggers. Just enter them as you would in the
command box: prefixed by <literal>/</literal>. If the action is simple
you can enter the statements there directly, if not, you can define a
function in your script file and call it from the trigger.</para>

<para>If the action is a Perl statement, and the
<replaceable>pattern</replaceable> contains bracketed expressions, you
can access the matched text in the brackets with the variables
<varname>$_[1]</varname>, <varname>$_[2]</varname>, and so on. In
<varname>$_[0]</varname> you will find the whole matched line.</para>

<para>Let us rewrite the previous example to be more complex:</para>

<example><title>A trigger with an action in Perl</title>
<programlisting>
$world-&gt;trigger('^(.*) has attacked you!$',
                '/$world-&gt;send("cast missile $_[1]")
</programlisting>
</example>

<para>Now, when a line consisting of some arbitrary text followed by
"<literal>has attacked you!</literal>" is received, the
<function>$world-&gt;send</function> will be called to send some text to
the World. This text consists of <userinput>cast missile</userinput>
followed by the text that was before "<literal>has attacked
you!</literal>", which is presumably the name of a mob. So if the
received line is "<literal>Sauron has attacked you!</literal>", the
command that will be sent is "<userinput>cast missile
Sauron</userinput>".</para>

<para>If you call a sub-routine as the trigger action, the matched
arguments are not automatically passed, so you need to pass them
manually. Since they are in the array <varname>@_</varname>, just pass
that whole array as the argument to the sub-routine. Inside the
sub-routine, they will be available as the sub-routine's arguments,
which incidentally means that they will be accessed in the exact same
way: with <varname>$_[1]</varname>, <varname>$_[2]</varname> and so
on.</para>

<para>Here's an example of a trigger that calls a sub-routine:</para>

<example><title>A trigger that calls a sub-routine</title>
<programlisting>
$world-&gt;trigger('^(.*) has attacked you!$',
                '/myGreatAttackSequence(@_)')
</programlisting>
</example>

<para>Naturally, you need to define the
<function>myGreatAttackSequence</function> sub-routine in your script
file. It will be called as the result of the trigger. The
<varname>@_</varname> array, containing the whole matched line and the
matched bracketed expressions is passed to the sub-routine as argument,
and its contents will be available to the sub-routine as its
paramenters.</para>


<sect2><title>Advanced Features of Triggers</title>

<para>Now that the basic usage of triggers has been explained, let us
see some more advanced features, which will require some small changes
in the way the <function>trigger</function> function is called.</para>

<para>In KildClient, gags are just triggers that are marked as such,
and they behave just like other triggers, with the exception that the
line that matched the pattern does not get printed in the screen. It
is possible to have a gag that executes an action when triggered, just
like with non-gag triggers, or it can be a simple gag, which prevents
the line from being printed but does nothing else.</para>

<para>To specify that a trigger is a gag when it is created an extra
argument is passed to the <function>trigger</function> function. For
those that know Perl, it is a reference to a hash, and this hash can
contain some attributes specifying the trigger's behaviour. For those
that do not understand the previous sentence, do not worry, the
examples should make the usage clear.</para>

<para>Let's create a simple gag to omit all that is said by Joe, a
very silly and annoying player:</para>

<example><title>A simple gag</title>
<programlisting>
$world-&gt;trigger('^Joe chats',
                '/$world-&gt;echonl("Joe said something silly here.")',
                { gag =&gt; 1 })
</programlisting>
</example>

<para>See the difference? There is a third parameter, enclosed in
curly braces <literal>{}</literal>, with the word
<literal>gag</literal>, an arrow, and the number 1. What that means is
that <literal>gag</literal> has the value 1, or, as usual in computer
languages, is true. (False would be zero.) The trigger is a gag, and
whenever a line starting with "<literal>Joe chats</literal>" is
received, it will not be printed. Instead, the code specified in the
action will be executed, and that will print a message that tells you
that Joe said something, but does not tell what, so you do not need to
worry.</para>

<para>That is good, but can get even better. We do not need to know
that Joe said something, it would be better if we could ignore him
altogether. And we can. It is not necessary to specify an action for a
gag. In this case, nothing will be done, but the matched line will not
be printed. So our example becomes:</para>

<example><title>A gag with no action</title>
<programlisting>
$world-&gt;trigger('^Joe chats',
                { gag =&gt; 1 })
</programlisting>
</example>

<para>The action has simply been omitted, but the argument that
specifies that we are dealing with a gag remains, naturally. As a
matter of fact, this kind of gag (with no action) is quite common, and
there is a shorter way to do that. The command below has the exact
same effect as the previous one:</para>

<example><title>A shortcut function to define gags</title>
<programlisting>
$world-&gt;gag('^Joe chats')
</programlisting>
</example>

<para>Sometimes you want to change the way a line is displayed, such
as highlighting it or part of it, or rearranging the information so
that it appears in another way. The way to do that is with a gag, and
an action that outputs the modified line. Heres a simple example that
changes the way a hypothetical chat channel is displayed:</para>

<example><title>Rewriting a line with gags</title>
<programlisting>
$world-&gt;trigger('^(.*) chats, \'(.*)\'',
                '/$world-&gt;echonl("[Chat] $_[1]: $_[2]")',
                { gag =&gt; 1 })
</programlisting>
</example>

<para>Remember that <varname>$_[0]</varname>, the first element of the
array <varname>@_</varname> contains the whole matched line, with ANSI
codes stripped. If you need the original string including ANSI codes,
you can find them in the variable <varname>$colorline</varname>. A
useful function you should check is <function>colorize</function> (see
<xref linkend="func:colorize" endterm="func:colorize.title"/>), which
allows easy printing of colored strings.</para>

<para>The <literal>gag</literal> attribute only controls whether the
line is displayed in the screen or not. If you have logging enabled
(see <xref linkend="chap:logging"/>), a the line that matched a
trigger with the <literal>gag</literal> attribute will be written in
the log file normally. If you want the line to be omitted from the log
file, you must set also the <literal>gaglog</literal> attribute. If it
is set, then the line will not be written to the log file. Note that
the two attributes are independent: you can gag the line from the
screen, from the log file, from both or from neither.</para>

<para>To make case be ignored when matching, use a very similar
construct as the above, but using the <literal>ignorecase</literal>
attribute:</para>

<example><title>A case-insensitive trigger</title>
<programlisting>
$world-&gt;trigger('^.* chats ".*joe.*"', '/callAttention()',
                { ignorecase =&gt; 1})
</programlisting>
</example>

<para>Another attribute that can be set for triggers is
<literal>keepexecuting</literal>. By default when a trigger matches,
no more checking is done. So if a line would match two or more
triggers, only the first would have a successful match and have its
action executed. The other ones wouldn't even have a chance to try a
match.</para>

<para>When a trigger has the <literal>keepexecuting</literal> flag
set, even if it matches it does not prevent other triggers from being
tried. So, if a second trigger matches, the actions of both will be
executed. Note, however, that unless this second trigger also has the
<literal>keepexecuting</literal> flag, trigger matching will
stop.</para>

<para>This flag is specified just like <literal>gag</literal>. Just
add the parameter <literal>{ keepexecuting =&gt; 1 }</literal> to the
function call. It is possible for a trigger to be both a gag and have
the <literal>keepexecuting</literal> flag. In this case, include both
in the last argument: <literal>{ gag =&gt; 1, keepexecuting =&gt; 1
}</literal>. Note it is just one argument, with both flags separated
by a comma. The order does not matter,
<literal>keepexecuting</literal> could have come before
<literal>gag</literal>.</para>

<para>If you are having trouble with triggers and want to be informed
whenver a trigger matches, enable the
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Debug Matches</guimenuitem>
</menuchoice>
menu. When this is enabled, information about each matched trigger
will be printed to stderr. (This means you must start KildClient from
a terminal to see the output.)</para>

</sect2>


<sect2 id="sec:trigger_rewriter"><title>Rewriter Triggers</title>

<para>Rewriter triggers are a special kind of trigger that allows
something not possible with ordinary triggers: changing the received
line so that futher triggers work on this changed line.</para>

<para>As mentioned above, the <varname>$colorline</varname> variable
holds the entire line that matched the trigger, including ANSI color
codes. Rewriter triggers can alter this variable, and then the other
triggers will match on this changed line.</para>

<para>Rewriter triggers run before normal triggers. Also, the
<literal>keepexecuting</literal> flag is not considered for them: they
never stop processing of other triggers, even if
<literal>keepexecuting</literal> is not set. The
<literal>gag</literal> and <literal>gaglog</literal> flags are also
not significant for a rewriter trigger, and they are ignore.</para>

<para>Let's see an example of where rewriter triggers can be useful.
Suppose you do not want to see an offensive word that might appear in
the MUD. A first attempt at filtering could be a trigger like
this:</para>

<example>
<title>A profanity filter, that unfortunately does not work</title>
<programlisting>
$world-&gt;trigger('fuck',
                '/$colorline =~ s/fuck/f***/; $world-&gt;echo($colorline)',
                { gag =&gt; 1 })
</programlisting>
</example>

<para>This works for simple cases, but it is most likely not what you
want. Suppose you have a trigger that captures messages sent from a
specific channel (such as the one for telepathic communications) and
does something, such as changing the presentation of the message or
sending them to another window. If someone sends a message over that
channel with the f-word, the channel-capture trigger will not work
because the line has already been caught the the profanity-filter
trigger above. You'll see the message with the bad word filtered, but
it will not be captured as a channel message.</para>

<para>You might think about setting the
<literal>keepexecuting</literal> flag in the profanity-filter trigger,
but that would not solve the problem. That trigger would match, and
print in the main window the line just with the word filtered. And
then the original line would match against the channel-capture
trigger, thus acting upon the channel message, but with the bad word
intact, because the trigger did not change the line. So you would end
up seeing the message twice, but neither case in the way you
want.</para>

<para>The solution to this problem is to use a rewriter trigger to
filter the bad word before other triggers have a chance to see the
line. Our profanity-filter trigger should be like this:</para>

<example>
<title>A profanity filter using a rewriter trigger</title>
<programlisting>
$world-&gt;trigger('fuck',
                '/$colorline =~ s/fuck/f***/',
                { rewriter =&gt; 1 })
</programlisting>
</example>

<para>Note that the line is not printed. Rewriter triggers generally
need not print anything, because if no other trigger matches the line,
it will be printed (with the changed contents). If another trigger
does, let this trigger decide what to do.</para>

<para>Now everything should work: when any line with the f-word is
seen, this word is filtered out and the line is changed. If this was a
channel message, the channel-capture trigger will see the line with
the offensive word filtered and display the message in your special
way without the bad word.</para>

</sect2>


<sect2 id="sec:edit_trigger_cmdline"><title>Editing Triggers</title>

<para>In the previous sections it was shown how to add triggers, but
nothing was told about how to change them after they are defined. This
and other points will be addressed in this section.</para>

<para>Before going into editing, let us see how to get a list of all
triggers that are currently defined for the World. Just use the
<function>$world-&gt;listtrigger</function> function without arguments.
You will be presented with a list of the currently defined
triggers.</para>

<para>There are several columns: <computeroutput>Num</computeroutput>
is the number of the trigger. Triggers are numbered sequentially
starting at zero. This number will be useful when we start editing
triggers. Next comes <computeroutput>gag</computeroutput>, which tells
whether the trigger is a gag (for the screen). Next is
<computeroutput>GLo</computeroutput>, which means "Gag from Log", and
shows whether the line is omitted (that is, not written) in the log
file also (if logging is enabled, of course). After that,
<computeroutput>Ena</computeroutput> tells whether the trigger is
enabled. Triggers that are disabled are not matched. This is a nice
way to stop a trigger, but keep it stored for later use. We will see
how to enable and disable triggers later in this section. Next there
is <computeroutput>KeE</computeroutput>, which reports the status of
the <literal>keepexecuting</literal> flag for the trigger. After that,
<computeroutput>IgC</computeroutput> specifies the case is being
ignored. The final two columns list the pattern and action of the
trigger.</para>

<para>The listing produced by <function>$world-&gt;listtrigger</function>
is compact, showing all triggers but possibly truncating the pattern
and/or action. If you give a trigger number as argument to
<function>listtrigger</function>, it will display that trigger's
information detailedly.</para>

<para>To edit a trigger, you need to know that trigger's number. (And
that can be discovered with the listing functions just described.) The
same function used to add triggers can also change existing ones, you
just need to pass the trigger number as the first argument.</para>

<para>Calling
<function>$world-&gt;trigger(<replaceable>number</replaceable>,
<replaceable>new pattern</replaceable>)</function> changes the pattern
of the trigger with that number. If you want to change the pattern and
action, include the action as a third argument:
<function>$world-&gt;trigger(<replaceable>number</replaceable>,
<replaceable>new pattern</replaceable>, <replaceable>new
action</replaceable>)</function>. What if you want to change only the
action? Since passing only one string argument would change the
pattern, this is done in a different way, using the same hash that is
used to pass attributes to the trigger. In brief, this is how you
would change only the action:
<function>$world-&gt;trigger(<replaceable>number</replaceable>, { action
=&gt; <replaceable>new action</replaceable> })</function>. Notice that
the action is passed as an attribute inside the curly braces. It is
also possible to change the pattern this way, just use the attribute
<literal>pattern</literal>.</para>

<para>Naturally, it is possible to attributes such as
<literal>gag</literal> or <literal>keepexecuting</literal>. The syntax
is the same, include the new value inside the curly braces. To clear
one of those flags, use the value 0, which means false. The example
below makes trigger number 2 stop being a gag, and at the same time
sets it not to prevent matching of other triggers:</para>

<example><title>Changing several attributes at once</title>
<programlisting>
$world-&gt;trigger(2,
                { gag =&gt; 0,
                  keepexecuting =&gt; 1 })
</programlisting>
</example>

<para>It is also possible, naturally, to change attributes such as
<literal>pattern</literal> or <literal>action</literal> at the same
time that <literal>gag</literal> or <literal>keepexecuting</literal>
are changed. All these attributes are equal, the only difference is
that since the pattern and action are used much more often, there is a
shorter way of specifying them. But even when you create a trigger you
can use this extended syntax. <xref linkend="ex:simplest_trigger"/>
could be also entered this way, with the exact same results:</para>

<example><title>A very simple trigger, in another way</title>
<programlisting>
$world-&gt;trigger({ pattern =&gt; 'has attacked you!',
                  action =&gt; 'wield sword'})
</programlisting>
</example>

<para>The final attribute for triggers is <literal>enabled</literal>.
It was mentioned briefly when we described how to list triggers. It
can be set just like the other attributes, and like
<literal>keepexecuting</literal> or <literal>gag</literal> it is
<emphasis>binary</emphasis>, that is, takes the values
<emphasis>true</emphasis> (represented by anything different from 0)
or <emphasis>false</emphasis> (represented by 0). When the value of
this attribute is true (which is the default), the trigger is matched
normally. When it is zero, received lines are not matched against it.
This way, disabling a trigger effectively turns if off, as if it did
not exist, but the trigger is still saved, and can be turned on again
when necessary.</para>

<para>Here's an example of disabling a trigger (number 3 in this
case):</para>

<example><title>Disabling a trigger, the long way</title>
<programlisting>
$world-&gt;trigger(3,
                { enabled =&gt; 0 })
</programlisting>
</example>

<para>However, there is a shorter way: the
<function>$world-&gt;distrigger</function> function disables the trigger
whose number is passed as argument. So the example above can be
rewritten in a shorter way as:</para>

<example><title>Disabling a trigger, the short way</title>
<programlisting>
$world-&gt;distrigger(3)
</programlisting>
</example>

<para>The corresponding function
<function>$world-&gt;enatrigger</function> enables the specified
trigger.</para>

<para>It is also possible to temporarily disable all triggers. Just
use the menu
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Disable Triggers</guimenuitem>
</menuchoice>
and this will prevent triggers from running. This does not change the
"enabled" status of any triggers, it just prevents all triggers from
running. When you select the menu again, triggers that were enabled
will run again, and those that were disabled will remain
disabled.</para>

<para>There are times when you want to delete a trigger. This is easy
to do, use the <function>$world-&gt;deltrigger</function> function. It
takes as argument the number of the trigger you wish to delete. Be
aware that once deleted it is not possible to recover the trigger
(unless you create it again). Many times just disabling the trigger is
a better idea. The second thing to note is that when you delete a
trigger the numbers of the other triggers may change, so be careful
when you try to delete several triggers in sequence.</para>

</sect2>


<sect2><title>Assigning Names to Triggers</title>

<para>It is possible to assign names to triggers. When a trigger has a
name, you can enable, disable, or delete it using its name instead of
its number.</para>

<para>To assign a name to a trigger, specify the
<literal>name</literal> attribute when creating it:</para>

<example><title>Creating a trigger with a name</title>
<programlisting>
$world-&gt;trigger('has attacked you!', 'wield sword',
                { name =&gt; 'attack' })
</programlisting>
</example>

<para>You can now disable this trigger with
<userinput>$world-&gt;distrigger('attack')</userinput>. The name can also
be used in the <function>$world-&gt;enatrigger</function>,
<function>$world-&gt;deltrigger</function> and
<function>$world-&gt;listtrigger</function> functions.</para>

<para>It is also possible to assign a name to an existing trigger.
Just edit it as described in <xref
linkend="sec:edit_trigger_cmdline"/>, passing the
<literal>name</literal> attribute. Use this same process to change the
name of a trigger.</para>

<para>Another feature of trigger names is that several triggers can
have the same name. In this case, all these triggers will be treated
as a single group. The functions above, when passed a trigger name,
will act upon all triggers of the group, that is, on all triggers with
that name.</para>

</sect2>


<sect2><title>Reordering Triggers</title>

<para>Triggers are tried from the first to the last, so in some cases
the order of the triggers matters. It is possible to move a trigger to
another position with the <function>$world-&gt;movetrigger</function>
function.</para>

<para>The function takes two parameters: the first is the name or
number of the trigger that you want to move. The second is the new
position that the trigger will take in the list. 0 means move the the
first position. If you specify a negative number or a number greater
than the number of triggers, the trigger will be moved to the end of
the list.</para>

<para>If there are several triggers with the same name, only the first
one found will be moved. And when a trigger is moved, other triggers
might move up or down to accomodate the change.</para>

</sect2>

</sect1>


<sect1 id="sec:import_export"><title>Importing and Exporting</title>

<para>You can export triggers, aliases, macros, timers, permanent
variables and hooks to a file, and them load these objects in another
World. This function is accessed via the World Editor.</para>

<para>To export some items, select them from the list. (You can select
several items by holding the <keysym>Control</keysym> key and
clicking.) Press the <guilabel>Export</guilabel> button, and a dialog
will open for you to select a file name. Select a name, press
<guilabel>Save</guilabel> and the selected items will be saved to the
file.</para>

<para>The export function is accessible from the editors for all
exportable objects (triggers, aliases, macros, timers, permanent
variables and hooks). By default, it only exports one kind of object,
the one currently displayed. But you can export more than one kind of
object to the same file (for example, triggers and aliases, or
aliases, macros and hooks, or even all of them). To do that, select
all the items you want from all the pages in the World Editor. Then,
from any page, select <guilabel>Export</guilabel>. From the dialog
that opens, click <guilabel>Items to export</guilabel>. Several check
boxes will appear. Mark the ones corresponding to the objects you want
to export, and all corresponding selected objects will be
imported.</para>

<para>After you have exported some items, you can import them in
another World, even in another machine. Just open one of the editors
(it doesn't matter which one, you can import triggers even from the
alias editor), and press <guilabel>Import</guilabel>. Select the file
from the dialog, and all items in the file will be imported and will
be included in the current World.</para>

</sect1>


<sect1 id="sec:test_triggers"><title>Testing Triggers</title>

<para>You can test your triggers to see how they would react to text
coming from the MUD. To do so, select the
<menuchoice>
  <guimenu>Input</guimenu>
  <guimenuitem>Test Triggers</guimenuitem>
</menuchoice>
menu item, or press the <guilabel>Test Triggers</guilabel> button from
the Trigger section of the World Editor.</para>

<para>You will see a dialog like this:</para>

<figure><title>The test triggers window</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/testtriggers.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The test triggers window.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In the first entry box, enter some text to be matched against
the triggers that are defined. This line will be matched as if it came
from the MUD. Then press the <guilabel>Send</guilabel> button to try
the triggers. Matching is done exactly for lines that come from the
server: only enabled triggers are tried, rewriter triggers are tried
first and change the line, the keep executing flag is verified, and so
on.</para>

<para>After pressing <guilabel>Send</guilabel>, the results are shown
in the second half of the window. The number of triggers that matched
is displayed, and also all the commands that would be processed if
that line came from the mud (if any). The line that would be printed
to the main window is also displayed. If any gag trigger matched, that
box will be empty indicating that no line will be printed. If no gag
triggers matched, the line could be different because a rewriter
trigger changed it. However, in most cases the line printed will be
the same as the line received. Finally, you are told if the line would
be written in the log file. If any gag log trigger matched the line,
then it would be omitted.</para>

<para>You can try the triggers against other lines, just enter them
and press <guilabel>Send</guilabel>. Any changes you make to the
triggers are used instantly, just press <guilabel>Send</guilabel>
again to try the same line against the new or changed triggers.</para>

</sect1>

</chapter>



<chapter id="chap:aliases"><title>Aliases</title>

<para>Aliases allow you to define shortcuts for simple commands. For
example, you can define <userinput>df</userinput> to be an alias to
<userinput>drink from fountain</userinput>, and then you can type only
<userinput>df</userinput> in the command line, and <userinput>drink
from fountain</userinput> will be sent to the mud.</para>

<para>However, in KildClient aliases can do much more. They allow you
to rewrite part of the input line. In the example above, what happened
is that <userinput>df</userinput> was replaced by <userinput>drink
from fountain</userinput>. Aliases such as these replace the entire
short command you type by a longer command, but you can also replace
part of the line. If a mob has a really long name, such as
Ingeloakastimizilian, you can define an alias "ing" that is replaced
by "Ingeloakastimizilian", and whenever you type
<userinput>ing</userinput>, even in the middle of another command, it
will be replaced by the full name.</para>

<para>Aliases are implemented as a substitution, just like Perl's
<literal>s///</literal> operator. (As a matter of fact, it
<emphasis>is</emphasis> implemented with <literal>s///</literal>.)
They consist of two parts: a <replaceable>pattern</replaceable> and a
<replaceable>substitution</replaceable>. These are just the two
arguments to the <literal>s///</literal> operator. Each command you
enter is tried against the <replaceable>pattern</replaceable>, and
when it matches the <replaceable>substitution</replaceable> is done.
This is more or less how the alias processing is done:</para>

<programlisting>
$line =~ s/$pattern/$substitution/;
</programlisting>

<para>Supposing <varname>$line</varname> holds the entered command,
<varname>$pattern</varname> the pattern and
<varname>$substitution</varname> the substitution. Then
<varname>$line</varname> is sent to the World, possibly having been
modified.</para>

<para>If you are having trouble with aliases and want to be informed
whenver an alias matches, enable the
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Debug Matches</guimenuitem>
</menuchoice>
menu. When this is enabled, information about each matched alias will
be printed to stderr. (This means you must start KildClient from a
terminal to see the output.)</para>



<sect1><title>Creating and Editing Aliases</title>

<para>The easiest way to create and alter aliases is from the World
Editor, the place where all settings of a World are altered (see <xref
linkend="chap:world_editor"/>).</para>

<para>Aliases are defined in the <guilabel>Aliases</guilabel> section
inside the <guilabel>Automation</guilabel> section. When you open that
section, you'll see a list of the defined aliases and some buttons
like this:</para>

<figure><title>The graphical Alias editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_aliases.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The graphical Alias editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The main part of the window is the list of defined aliases. The
columns are as follows:</para>

<itemizedlist>
  <listitem><para><guilabel>Enabled</guilabel> specifies whether the
  alias is enabled or not. Aliases that are not enabled are not active
  and will not be tried when a command is entered, but they remain in
  the list so that they can later be enabled again.</para></listitem>

  <listitem><para><guilabel>Name</guilabel> is a name that is assigned
  to an alias. This helps you identify the alias' purpose and is
  useful when editing an alias via the command line (as described in
  <xref linkend="sec:edit_alias_cmdline"/>). Assigning a name to an
  alias is optional.</para></listitem>

  <listitem><para><guilabel>Pattern</guilabel> and
  <guilabel>Substitution</guilabel> are the parameters for the alias,
  and they define the alias' action, as described above.</para></listitem>

  <listitem><para><guilabel>I Case</guilabel> (for "Ignore Case"), if
  set, means the case is not considered while matching the pattern,
  that is, a case-insensitive match is done.</para></listitem>

  <listitem><para><guilabel>Eval as Perl</guilabel> controls how the
  alias is evaluated. This option will be described
  later.</para></listitem>

  <listitem><para><guilabel>Plugin</guilabel>: if this is non-empty,
  it means that the alias belongs to a plugin (and the name of the
  plugin is displayed). However, by default plugin aliases are not
  displayed. See <xref linkend="sec:we_advanced"/> for information on
  how to display plugin aliases here.</para></listitem>
</itemizedlist>


<sect2 id="sec:add_alias_gui"><title>Adding Aliases</title>

<para>To add a new alias, press the <guilabel>Add</guilabel> button.
This will open a window for you to edit the new alias' parameters:</para>

<figure><title>The window to edit aliases</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_alias_edit.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to edit aliases.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>What can be set represents the columns described above. The only
thing that needs explanation is the <guilabel>Eval Substitution as
Perl statement</guilabel> option, corresponding to the <guilabel>Eval
as Perl</guilabel> column. As mentioned before, aliases are actually a
substitution, using Perl's <literal>s//</literal> construct. It is
also possible to have aliases that use a <literal>s//e</literal>
construct, that is, whose substitution is actually composed of Perl
statements evaluated when a match is found. When that option is
enabled, the substitution is evaluated as a Perl statement.</para>

<para>When you are finished, press <guilabel>OK</guilabel> and the
alias will be added. If you change your mind, press
<guilabel>Cancel</guilabel> and the alias will not be added.</para>

<para>To see some things aliases can do, read <xref
linkend="sec:alias_cmdline"/>. If you want to try the aliases
described there, you can create them from the World Editor.</para>

</sect2>


<sect2><title>Altering Aliases</title>

<para>To edit an alias, select it by clicking its line in the list
(the line will be highlighted), and press the
<guilabel>Edit</guilabel> button. A window like the one used for
adding aliases (see <xref linkend="sec:add_alias_gui"/>) will be
opened, filled with the alias' parameters. Change what you want, and
press the <guilabel>OK</guilabel> to commit the changes. If, however,
you change you mind, press <guilabel>Cancel</guilabel> and the changes
will be not be made, the alias will remain as it was before.</para>

<para>Another shorter way to edit an alias is to double click its line
in the list.</para>

<para>It is also possible to change the value of the
<guilabel>Enabled</guilabel> and <guilabel>Eval as Perl</guilabel>
flags directly from the alias list. Make sure that the alias you want
to change is selected, and click in the check button. The state will
be toggled.</para>

<para>To delete an alias, select it and press the
<guilabel>Delete</guilabel> button. You will be asked for
confirmation, and can cancel the operation, but once deleted, you
cannot recover the alias. If you want, you can disable this
confirmation dialog, but if you do so and click the
<guilabel>Delete</guilabel> button, the only way to undo your action
will be creating the alias again. See <xref
linkend="sec:we_advanced"/>. To delete several aliases at once, select
them all and press <guilabel>Delete</guilabel>.</para>

<para>The final thing that needs to be explained with regard to
aliases is how to reorder them. Aliases as tried from the first one to
the last, so in a few cases the order might matter. To move an alias
up or down in the list, select it and press the corresponding
button.</para>

</sect2>

</sect1>



<sect1 id="sec:alias_cmdline">
<title>Defining Aliases in the Command Line</title>

<para>For those more used to Perl and to command lines, it is also
possible to define and alter aliases from the command line. This is
done with a series of Perl function.</para>

<para>Aliases are defined with the
<function>$world-&gt;alias</function> function. This function works
similarly to <function>$world-&gt;trigger</function> (described in
<xref linkend="chap:triggers"/>).</para>

<para>The simplest way to call the function is with two arguments:
<function>$world-&gt;alias(<replaceable>pattern</replaceable>,
<replaceable>substitution</replaceable>)</function>. This defines an
alias with the given <replaceable>pattern</replaceable> and
<replaceable>substitution</replaceable>. For example, our
<userinput>df</userinput> alias would be created as follows:</para>

<example><title>A simple alias</title>
<programlisting>
$world-&gt;alias('^df$', 'drink from fountain')
</programlisting>
</example>

<para>You might be wondering why we use "<literal>^df$</literal>" and
not only "<literal>df</literal>". Remember that aliases are just
substitutions, and the pattern is a regular expression. If the anchors
(that is, <literal>^</literal> and <literal>$</literal>) were not
present, it would match against <userinput>df</userinput> anywhere in
the line, and substitute this <userinput>df</userinput> even in the
middle of words. <userinput>wonder</userinput> would become
<userinput>wodrink from fountainder</userinput>. At times a behaviour
like this (substituting anywhere) might be desirable, but in our case
we want it to substitute only the whole command
<userinput>df</userinput>, so we use the anchors.</para>

<para>As an example of an alias that does not match only the exact
command, consider this one:</para>

<example><title>A slightly more complex alias</title>
<programlisting>
$world-&gt;alias('^gra ', 'chat CONGRATULATIONS, ')
</programlisting>
</example>

<para>Whenever you enter a command that starts with
<userinput>gra</userinput> followed by a space, that part
(<userinput>gra</userinput> and the space) is replaced by the given
pattern. So if you enter <userinput>gra Bob</userinput>, what will be
sent to the MUD is <userinput>chat CONGRATULATIONS,
Bob</userinput>.</para>

<para>Since aliases are just a substitution, you can define bracketed
expressions in the pattern and then use <literal>$1</literal>,
<literal>$2</literal>, and so on in the substitution. Let us increment
the above example to add something to the end. We will need a
bracketed expression:</para>

<example><title>An alias that uses bracketed expressions</title>
<programlisting>
$world-&gt;alias('^gra (.*)$', 'chat CONGRATULATIONS, $1!!!')
</programlisting>
</example>

<para>It should be easy to understand. <literal>$1</literal> in the
substituion is replaced by what goes after
<userinput>gra</userinput>.</para>


<sect2><title>Advanced Features of Aliases</title>

<para>As mentioned in <xref linkend="sec:add_alias_gui"/>, aliases
can use a <literal>s//e</literal> construct, that is, whose
substitution is actually composed of Perl statements evaluated when a
match is found.</para>

<para>To use that feature, specify an alias like this:</para>

<example><title>An alias whose substitution is evaluated:</title>
<programlisting>
$world-&gt;alias('calc\((.*)\)', 'eval "$1"',
              { perleval =&gt; 1})
</programlisting>
</example>

<para>See the difference? There is a third parameter, enclosed in
curly braces <literal>{}</literal>, with the word
<literal>perleval</literal>, an arrow, and the number 1. What that
means is that <literal>perleval</literal> has the value 1, or, as
usual in computer languages, is true. (False would be zero.) This
syntax will be explained in more detail in <xref
linkend="sec:edit_alias_cmdline"/>.</para>

<para>The alias allows you to write something like that:
<userinput>gossip 2+3 = calc(2+3)</userinput> and have the result of
the calculation sent to the MUD. (Or any other Perl statement to be
evaluated, actually.)</para>

<para>To specify a case-insensitive match, use the
<literal>ignorecase</literal> attribute:</para>

<example><title>A case-insensitive alias</title>
<programlisting>
$world-&gt;alias('^df$', 'drink from fountain',
              { ignorecase =&gt; 1 })
</programlisting>
</example>

</sect2>


<sect2 id="sec:edit_alias_cmdline"><title>Editing Aliases</title>

<para>Before going into editing, let us see how to get a list of all
aliases that are currently defined for the World. Just use the
<function>$world-&gt;listalias</function> function without arguments. You
will be presented with a list of the currently defined aliases.</para>

<para>There are four columns: <computeroutput>Num</computeroutput> is
the number of the alias. Aliases are numbered sequentially starting at
zero. This number will be useful when we start editing aliases. After
that, <computeroutput>Ena</computeroutput> tells whether the alias is
enabled. Aliases that are disabled are not tried. This is a nice way
to stop an alias from working, but keep it stored for later use. We
will see how to enable and disable aliases later in this section. The
final two columns list the pattern and substitution of the
alias.</para>

<para>The listing produced by <function>$world-&gt;listalias</function>
is compact, showing all aliases but possibly truncating the pattern
and/or substitution. If you give an alias number as argument to
<function>listalias</function>, it will display that alias's
information detailedly.</para>

<para>To edit an alias, you need to know that alias's number. (And
that can be discovered with the listing functions just described.) The
same function used to add aliases can also change existing ones, you
just need to pass the alias number as the first argument.</para>

<para>Calling
<function>$world-&gt;alias(<replaceable>number</replaceable>,
<replaceable>new pattern</replaceable>)</function> changes the pattern
of the alias with that number. If you want to change the pattern and
substitution, include the substitution as a third argument:
<function>$world-&gt;alias(<replaceable>number</replaceable>,
<replaceable>new pattern</replaceable>, <replaceable>new
substitution</replaceable>)</function>. What if you want to change
only the substitution? Since passing only one string argument would
change the pattern, this is done in a different way. In brief, this is
how you would change only the substitution:
<function>$world-&gt;alias(<replaceable>number</replaceable>, {
substitution =&gt; <replaceable>new substitution</replaceable>
})</function>. Notice that the substitution is passed as an attribute
inside the curly braces. It is also possible to change the pattern
this way, just use the attribute <literal>pattern</literal>.</para>

<para>One other attribute of aliases is <literal>enabled</literal>. It
was mentioned briefly when we described how to list aliases. It can be
set just like the other attributes and is <emphasis>binary</emphasis>,
that is, takes the values <emphasis>true</emphasis> (represented by
anything different from 0) or <emphasis>false</emphasis> (represented
by 0). When the value of this attribute is true (which is the
default), the alias is tried normally. When it is zero, commands are
not tried against it. This way, disabling an alias effectively turns
if off, as if it did not exist, but the alias is still saved, and can
be turned on again when necessary.</para>

<para>Here's an example of disabling an alias (number 3 in this
case):</para>

<example><title>Disabling an alias, the long way</title>
<programlisting>
$world-&gt;alias(3,
              { enabled =&gt; 0 })
</programlisting>
</example>

<para>However, there is a shorter way: the
<function>$world-&gt;disalias</function> function disables the alias
whose number is passed as argument. So the example above can be
rewritten in a shorter way as:</para>

<example><title>Disabling an alias, the short way</title>
<programlisting>
$world-&gt;disalias(3)
</programlisting>
</example>

<para>The corresponding function <function>$world-&gt;enaalias</function>
enables the specified alias.</para>

<para>It is also possible to temporarily disable all aliases. Just use
the menu
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Disable Aliases</guimenuitem>
</menuchoice>
and this will prevent aliases from being used. This does not change
the "enabled" status of any aliases, it just prevents all aliases from
being executed. When you select the menu again, aliases that were
enabled will be matched again, and those that were disabled will
remain disabled.</para>

<para>There are times when you want to delete an alias. This is easy
to do, use the <function>$world-&gt;delalias</function> function. It
takes as argument the number of the alias you wish to delete. Be aware
that once deleted it is not possible to recover the alias (unless you
create it again). Many times just disabling the alias is a better
idea. The second thing to note is that when you delete an alias the
numbers of the other aliases may change, so be careful when you try to
delete several aliases in sequence.</para>

</sect2>


<sect2><title>Assigning Names to Aliases</title>

<para>It is possible to assign names to aliases. When an alias has a
name, you can enable, disable, or delete it using its name instead of
its number.</para>

<para>To assign a name to an alias, specify the
<literal>name</literal> attribute when creating it:</para>

<example><title>Creating an alias with a name</title>
<programlisting>
$world-&gt;alias('^df$', 'drink from fountain',
              { name =&gt; 'drink' })
</programlisting>
</example>

<para>You can now disable this alias with
<userinput>$world-&gt;disalias('drink')</userinput>. The name can also
be used in the <function>$world-&gt;enaalias</function>,
<function>$world-&gt;delalias</function> and
<function>$world-&gt;listalias</function> functions.</para>

<para>It is also possible to assign a name to an existing alias.
Just edit it as described in <xref linkend="sec:edit_alias_cmdline"/>,
passing the <literal>name</literal> attribute. Use this same process
to change the name of an alias.</para>

<para>Another feature of alias names is that several aliases can have
the same name. In this case, all these aliases will be treated as a
single group. The functions above, when passed an alias name, will act
upon all aliases of the group, that is, on all aliases with that
name.</para>

</sect2>


<sect2><title>Reordering Aliases</title>

<para>Aliases are tried from the first to the last, so in some cases
the order of the aliases matters. It is possible to move an alias to
another position with the <function>$world-&gt;movealias</function>
function.</para>

<para>The function takes two parameters: the first is the name or
number of the alias that you want to move. The second is the new
position that the alias will take in the list. 0 means move the the
first position. If you specify a negative number or a number greater
than the number of aliases, the alias will be moved to the end of the
list.</para>

<para>If there are several aliases with the same name, only the first
one found will be moved. And when an alias is moved, other aliases
might move up or down to accomodate the change.</para>

</sect2>

</sect1>

</chapter>



<chapter id="chap:macros"><title>Macros</title>

<para>Macros are, in a way, similar to aliases. They allow you to send
commands to the MUD in an easier way. Aliases allow you to associate
commands with shortcuts (typing a three-letter command to send a much
more complex command, for example). Macros allow you to associate a
command with a keypress. You could associate, for example,
<keysym>F5</keysym> with the command <userinput>drink from
fountain</userinput>, and then you would only need to press
<keysym>F5</keysym> to send that command to the MUD.</para>

<para>The commands need not be complex or big: you could associate the
arrow keys with macros that send movement commands, and you would be
able to move around the MUD using the arrow keys.</para>

<para>Macros consist of a <replaceable>key</replaceable> and an
<replaceable>action</replaceable>. The
<replaceable>action</replaceable> represents what is sent to the MUD
when the macro is run. It can be a single command to send, several
commands separated by <literal>%;</literal>, or something to be
executed by Perl, if it starts with <literal>/</literal>.</para>


<sect1><title>Creating and Editing Macros</title>

<para>The easiest way to create and alter macros is from the World
Editor, the place where all settings of a World are altered (see <xref
linkend="chap:world_editor"/>).</para>

<para>Macro are defined in the <guilabel>Macros</guilabel> section
inside the <guilabel>Automation</guilabel> section. When you open that
section, you'll see a list of the defined macros and some buttons
like this:</para>

<figure><title>The graphical Macro editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_macros.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The graphical Macro editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The main part of the window is the list of defined macros. The
columns are as follows:</para>

<itemizedlist>
  <listitem><para><guilabel>Enabled</guilabel> specifies whether the
  macro is enabled or not. Macros that are not enabled are not active
  and will not be run even if their key is pressed, but they remain in
  the list so that they can later be enabled again.</para></listitem>

  <listitem><para><guilabel>Name</guilabel> is a name that is assigned
  to a macro. This helps you identify the macro's purpose and is
  useful when editing a macro via the command line (as described in
  <xref linkend="sec:edit_macro_cmdline"/>). Assigning a name to a
  macro is optional.</para></listitem>

  <listitem><para><guilabel>Key</guilabel> is the key that activates
  the macro.</para></listitem>

  <listitem><para><guilabel>Action</guilabel> is the action that is
  run when the key is pressed.</para></listitem>

  <listitem><para><guilabel>Plugin</guilabel>: if this is non-empty,
  it means that the macro belongs to a plugin (and the name of the
  plugin is displayed). However, by default plugin macros are not
  displayed. See <xref linkend="sec:we_advanced"/> for information on
  how to display plugin macros here.</para></listitem>
</itemizedlist>


<sect2 id="sec:add_macro_gui"><title>Adding Macros</title>

<para>To add a new macro, press the <guilabel>Add</guilabel> button.
This will open a window for you to edit the new macro's parameters:</para>

<figure><title>The window to edit macros</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_macro_edit.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to edit macros.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>What can be set represents the columns described above. To
define the key, press the key combination desired in the text box for
<guilabel>Key</guilabel> and the appropriate key code will be
inserted.</para>

<para>When you are finished, press <guilabel>OK</guilabel> and the
macro will be added. If you change your mind, press
<guilabel>Cancel</guilabel> and the macro will not be added.</para>

<para>To see some things macros can do, read <xref
linkend="sec:macro_cmdline"/>. If you want to try the macros described
there, you can create them from the World Editor.</para>

</sect2>


<sect2><title>Altering Macros</title>

<para>To edit a macro, select it by clicking its line in the list
(the line will be highlighted), and press the
<guilabel>Edit</guilabel> button. A window like the one used for
adding macro (see <xref linkend="sec:add_macro_gui"/>) will be
opened, filled with the macro's parameters. Change what you want,
and press the <guilabel>OK</guilabel> to commit the changes. If,
however, you change you mind, press <guilabel>Cancel</guilabel> and
the changes will be not be made, the macro will remain as it was
before.</para>

<para>Another shorter way to edit a macro is to double click its
line in the list.</para>

<para>It is also possible to change the value of the enabled option
directly from the macro list. Make sure that the macro you want to
change is selected, and click in the check button. The state will be
toggled.</para>

<para>To delete a macro, select it and press the
<guilabel>Delete</guilabel> button. You will be asked for
confirmation, and can cancel the operation, but once deleted, you
cannot recover the macro. If you want, you can disable this
confirmation dialog, but if you do so and click the
<guilabel>Delete</guilabel> button, the only way to undo your action
will be creating the macro again. See <xref
linkend="sec:we_advanced"/>. To delete several macros at once, select
them all and press <guilabel>Delete</guilabel>.</para>

<para>The final thing that needs to be explained with regard to
macros is how to reorder them. Macros as tried from the first one
to the last, so in a few cases the order might matter. To move a
macro up or down in the list, select it and press the corresponding
button.</para>

</sect2>

</sect1>


<sect1 id="sec:macro_cmdline">
<title>Defining Macros in the Command Line</title>

<para>For those more used to Perl and to command lines, it is also
possible to define and alter macros from the command line. This is
done with a series of Perl function.</para>

<para>Macros are set defining, as mentioned above, a
<replaceable>key</replaceable> and an
<replaceable>action</replaceable>. The <replaceable>key</replaceable>
is key keycode for the key you wish to assign the macro to. The
easiest way to get the keycode for a given key is with the
<function>$world-&gt;getkeycode</function> function. This function takes
no parameters. When run, it prompts you to press a key, and then
prints the keycode for the key. It also returns the keycode as a
string, so you can save it in a variable and use when defining the
macro.</para>

<para>Here's a way to define a macro:</para>

<example><title>Defining a macro</title>
<screen>
<userinput>/$key = $world-&gt;getkeycode</userinput>
<computeroutput>Press a key to get its keycode.</computeroutput>
<replaceable>Press the F5 key</replaceable>
<computeroutput>Key code: F5</computeroutput>
<userinput>/$world-&gt;macro($key, 'drink from fountain')</userinput>
</screen>
</example>

<para>The above session shows how to assign <userinput>drink from
fountain</userinput> to the <keysym>F5</keysym> key. Note that
<function>$world-&gt;getkeycode</function> prompts you for a key and
prints its keycode. Additionally, the keycode is returned, and it is
stored in the <varname>$key</varname> variable. This variable is used
as the first argument to the <function>$world-&gt;macro</function>
function, that takes two arguments: the keycode and the action. We
could have entered <literal>'F5'</literal> directly, but using the
keycode returned by <function>$world-&gt;getkeycode</function> is easier
and less error-prone.</para>

<para>That's pretty much all about defining macros. They do not take
arguments, it is all about executing simple commands. Other things
that could be done are executing several commands (separating them
with <literal>%;</literal>) or executing a Perl statement or
function.</para>


<sect2 id="sec:edit_macro_cmdline"><title>Editing Macros</title>

<para>Before going into editing, let us see how to get a list of all
macros that are currently defined for the World. Just use the
<function>$world-&gt;listmacro</function> function without arguments. You
will be presented with a list of the currently defined macros.</para>

<para>There are four columns: <computeroutput>Num</computeroutput> is
the number of the macro. Macros are numbered sequentially starting at
zero. This number will be useful when we start editing them. After
that, <computeroutput>Ena</computeroutput> tells whether the macro is
enabled. Macros that are disabled are not executed even if the key is
pressed. This is a nice way to stop a macro from working, but keep it
stored for later use. We will see how to enable and disable macros
later in this section. The final two columns list the keycode and
action of the alias.</para>

<para>The listing produced by <function>$world-&gt;listmacro</function>
is compact, showing all macros but possibly truncating the keycode
and/or action. If you give a macro number as argument to
<function>listmacro</function>, it will display that macro's
information detailedly.</para>

<para>To edit a macro, you need to know that macro's number. (And that
can be discovered with the listing functions just described.) The same
function used to add macros can also change existing ones, you just
need to pass the macro number as the first argument.</para>

<para>Calling
<function>$world-&gt;macro(<replaceable>number</replaceable>,
<replaceable>new keycode</replaceable>)</function> changes the key of
the macro with that number. If you want to change the key and action,
include the substitution as a third argument:
<function>$world-&gt;macro(<replaceable>number</replaceable>,
<replaceable>new key</replaceable>, <replaceable>new
action</replaceable>)</function>. What if you want to change only the
action? Since passing only one string argument would change the key,
this is done in a different way. In brief, this is how you would
change only the key:
<function>$world-&gt;macro(<replaceable>number</replaceable>, { action =&gt;
<replaceable>new action</replaceable> })</function>. Notice that the
key is passed as an attribute inside the curly braces. It is also
possible to change the key this way, just use the attribute
<literal>key</literal>.</para>

<para>The only attribute for macros, besides the key and action, is
<literal>enabled</literal>. It was mentioned briefly when we described
how to list macros. It can be set just like the other attributes and
is <emphasis>binary</emphasis>, that is, takes the values
<emphasis>true</emphasis> (represented by anything different from 0)
or <emphasis>false</emphasis> (represented by 0). When the value of
this attribute is true (which is the default), the macro is run
normally. When it is zero, even if the key is pressed, the macros is
not run. This way, disabling an alias effectively turns if off, as if
it did not exist, but the macro is still saved, and can be turned on
again when necessary.</para>

<para>Here's an example of disabling a macro (number 3 in this
case):</para>

<example><title>Disabling a macro, the long way</title>
<programlisting>
$world-&gt;macro(3,
              { enabled =&gt; 0 })
</programlisting>
</example>

<para>However, there is a shorter way: the
<function>$world-&gt;dismacro</function> function disables the meacro whose
number is passed as argument. So the example above can be rewritten in
a shorter way as:</para>

<example><title>Disabling a macro, the short way</title>
<programlisting>
$world-&gt;dismacro(3)
</programlisting>
</example>

<para>The corresponding function <function>$world-&gt;enamacro</function>
enables the specified macro.</para>

<para>It is also possible to temporarily disable all macros. Just use
the menu
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Disable Macros</guimenuitem>
</menuchoice>
and this will prevent macros from running. This does not change the
"enabled" status of any macros, it just prevents all macros from
running. When you select the menu again, macros that were enabled will
run again, and those that were disabled will remain disabled.</para>

<para>There are times when you want to delete a macro. This is easy to
do, use the <function>$world-&gt;delmacro</function> function. It takes
as argument the number of the macro you wish to delete. Be aware that
once deleted it is not possible to recover the macro (unless you
create it again). Many times just disabling the macro is a better
idea. The second thing to note is that when you delete a macro the
numbers of the other macros may change, so be careful when you try to
delete several macros in sequence.</para>

</sect2>


<sect2><title>Assigning Names to Macros</title>

<para>It is possible to assign names to macros. When a macro has a
name, you can enable, disable, or delete it using its name instead of
its number.</para>

<para>To assign a name to a macro, specify the <literal>name</literal>
attribute when creating it:</para>

<example><title>Creating a macro with a name</title>
<programlisting>
$world-&gt;macro($key, 'drink from fountain',
              { name =&gt; 'drink' })
</programlisting>
</example>

<para>You can now disable this macro with
<userinput>$world-&gt;dismacro('drink')</userinput>. The name can also be
used in the <function>$world-&gt;enamacro</function>,
<function>$world-&gt;delmacro</function> and
<function>$world-&gt;listmacro</function> functions.</para>

<para>It is also possible to assign a name to an existing macro. Just
edit it as described in <xref linkend="sec:edit_macro_cmdline"/>,
passing the <literal>name</literal> attribute. Use this same process
to change the name of a macro.</para>

<para>Another feature of macro names is that several macros can have
the same name. In this case, all these macros will be treated as a
single group. The functions above, when passed a macro name, will act
upon all macros of the group, that is, on all macros with that
name.</para>

</sect2>


<sect2><title>Reordering Macros</title>

<para>Macros are tried from the first to the last, so in some cases
the order of the macros matters. It is possible to move an macro to
another position with the <function>$world-&gt;movemacro</function>
function.</para>

<para>The function takes two parameters: the first is the name or
number of the macro that you want to move. The second is the new
position that the macro will take in the list. 0 means move the the
first position. If you specify a negative number or a number greater
than the number of macros, the macro will be moved to the end of the
list.</para>

<para>If there are several macros with the same name, only the first
one found will be moved. And when an macro is moved, other macros
might move up or down to accomodate the change.</para>

</sect2>

</sect1>

</chapter>



<chapter><title>Timers</title>

<para>Timers allow you to execute commands repeatedly at fixed
intervals, and also to specify a command to be executed later.</para>

<para>Timers have to mandatory attributes: an
<replaceable>interval</replaceable> in seconds, that represents how
often the timer is fired, and an <replaceable>action</replaceable>,
that is the command that is executed. Just like in other places, the
action can be a text that is sent to the MUD, or it can be something
run with Perl.</para>

<para>It is possible to define timers that execute only a fixed number
of times. This is the timer's <replaceable>repeat count</replaceable>.
Whenever the timer is executed, this count is decreased, and when it
reaches zero, the timer is disabled, and will only execute again if
reenabled manually. A timer can also be temporary: in this case, when
the repeat count reaches zero, it is deleted and not only
disabled. A repeat count of -1 means that the timer is executed
indefinitely.</para>

<para>A timer with a repeat count of one is executed only once. Since
the first execution only happens <replaceable>interval</replaceable>
seconds after it is defined, this allows you to define a command to be
executed after some specified time. If it is marked as temporary, the
timer will be deleted after it is run this one time.</para>


<sect1><title>Creating and Editing Timers</title>

<para>The easiest way to create and alter timers is from the World
Editor, the place where all settings of a World are altered (see <xref
linkend="chap:world_editor"/>).</para>

<para>Timer are defined in the <guilabel>Timers</guilabel> section
inside the <guilabel>Automation</guilabel> section. When you open that
section, you'll see a list of the defined timers and some buttons
like this:</para>

<figure><title>The graphical Timer editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_timers.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The graphical Timer editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>The main part of the window is the list of defined timers. The
columns are as follows:</para>

<itemizedlist>
  <listitem><para><guilabel>Enabled</guilabel> specifies whether the
  timer is enabled or not. Timers that are not enabled are not active
  and will not be run, but they remain in the list so that they can
  later be enabled again.</para></listitem>

  <listitem><para><guilabel>Name</guilabel> is a name that is assigned
  to a timer. This helps you identify the timer's purpose and is
  useful when editing a timer via the command line (as described in
  <xref linkend="sec:edit_timer_cmdline"/>). Assigning a name to a
  timer is optional.</para></listitem>

  <listitem><para><guilabel>Interval</guilabel> is the interval
  between timer activations, as described above.</para></listitem>

  <listitem><para><guilabel>Count</guilabel> is the repeat count, as
  described above.</para></listitem>

  <listitem><para><guilabel>Action</guilabel> is the action that is
  run when the timer fires.</para></listitem>

  <listitem><para><guilabel>Temp</guilabel> indicates whether the
  timer is <emphasis>temporary</emphasis> or not. Temporary timers are
  deleted automatically when their repeat count reaches
  0.</para></listitem>

  <listitem><para><guilabel>Plugin</guilabel>: if this is non-empty,
  it means that the timer belongs to a plugin (and the name of the
  plugin is displayed). However, by default plugin timers are not
  displayed. See <xref linkend="sec:we_advanced"/> for information on
  how to display plugin timers here.</para></listitem>
</itemizedlist>


<sect2 id="sec:add_timer_gui"><title>Adding Timers</title>

<para>To add a new timer, press the <guilabel>Add</guilabel> button.
This will open a window for you to edit the new timer's parameters:</para>

<figure><title>The window to edit timers</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_timer_edit.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to edit timers.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>What can be set represents the columns described above.</para>

<para>When you are finished, press <guilabel>OK</guilabel> and the
timer will be added. If you change your mind, press
<guilabel>Cancel</guilabel> and the timer will not be added.</para>

<para>To see some things timers can do, read <xref
linkend="sec:timer_cmdline"/>. If you want to try the timers described
there, you can create them from the World Editor.</para>

</sect2>


<sect2><title>Altering Timers</title>

<para>To edit a timer, select it by clicking its line in the list
(the line will be highlighted), and press the
<guilabel>Edit</guilabel> button. A window like the one used for
adding timer (see <xref linkend="sec:add_timer_gui"/>) will be
opened, filled with the timer's parameters. Change what you want,
and press the <guilabel>OK</guilabel> to commit the changes. If,
however, you change you mind, press <guilabel>Cancel</guilabel> and
the changes will be not be made, the timer will remain as it was
before.</para>

<para>Another shorter way to edit a timer is to double click its
line in the list.</para>

<para>It is also possible to change the value of the binary options
(those represented by a check box) directly from the timer list.
Make sure that the timer you want to change is selected, and click
in the check button. The state will be toggled.</para>

<para>To delete a timer, select it and press the
<guilabel>Delete</guilabel> button. You will be asked for
confirmation, and can cancel the operation, but once deleted, you
cannot recover the timer. If you want, you can disable this
confirmation dialog, but if you do so and click the
<guilabel>Delete</guilabel> button, the only way to undo your action
will be creating the timer again. See <xref
linkend="sec:we_advanced"/>. To delete several timers at once, select
them all and press <guilabel>Delete</guilabel>.</para>

<para>The final thing that needs to be explained with regard to
timers is how to reorder them. Timers as tried from the first one
to the last, so in a few cases the order might matter. To move a
timer up or down in the list, select it and press the corresponding
button.</para>

</sect2>

</sect1>


<sect1 id="sec:timer_cmdline">
<title>Defining Timers in the Command Line</title>

<para>For those more used to Perl and to command lines, it is also
possible to define and alter timers from the command line. This is
done with a series of Perl function.</para>

<para>Timers are created with the <function>$world-&gt;timer</function>
function. It is similar to other functions for adding triggers,
aliases and macros, but the hash reference with attributes (the thing
inside <literal>{}</literal>) must always be used.</para>

<para>Let us see an example of defining a timer that sends
"<userinput>who</userinput>" once a minute:</para>

<example><title>A simple timer</title>
<programlisting>
$world-&gt;timer({ interval =&gt; 60,
                action =&gt; 'who' })
</programlisting>
</example>

<para>Note that the interval is specified in seconds.</para>

<para>Our second example will be of a timer that executes a specified
number of times:</para>

<example><title>A timer that executes only five times</title>
<programlisting>
$count = 5;
$world-&gt;timer({ interval =&gt; 10,
                count =&gt; 5,
                action =&gt; '/$world-&gt;send("chat The count is at $count"); --$count' })
</programlisting>
</example>

<para>In these two commands, first a variable that will be used in the
timer is defined. Then the timer is created, specifying
<replaceable>count</replaceable> as 5, so that it is executed only
five times. The timer's action is to send commands counting down to
one. When the count reaches one, the timer is disabled, because it has
already executed five times.</para>

<para>Now let us see a temporary timer:</para>

<example><title>A one-shot timer</title>
<programlisting>
$world-&gt;timer({ interval =&gt; 30,
                count =&gt; 1,
                temporary =&gt; 1,
                action =&gt; 'say 30 seconds have elapsed' })
</programlisting>
</example>

<para>This timer has a <replaceable>count</replaceable> of one,
meaning it will only be executed once. Also,
<replaceable>temporary</replaceable> is defined as true, which means
that after it is executed (which will happen in 30 seconds), the timer
will be erased.</para>

<para>Of course, a temporary timer does not need to have a
<replaceable>count</replaceable> of one. The countdown timer above
could have been made temporary if it was not needed after it reached
one.</para>


<sect2 id="sec:edit_timer_cmdline"><title>Editing Timers</title>

<para>Before going into editing, let us see how to get a list of all
timers that are currently defined for the World. Just use the
<function>$world-&gt;listtimer</function> function without arguments. You
will be presented with a list of the currently defined timers.</para>

<para>There are several columns: <computeroutput>Num</computeroutput>
is the number of the timer. Timers are numbered sequentially starting
at zero. This number will be useful when we start editing timers.
After that, <computeroutput>Int</computeroutput> is the interval (in
seconds) between timer firings. Next comes
<computeroutput>Count</computeroutput>, which is the number of times
the timer will still be fired before being disabled or erased. If the
value is -1, that means that it will execute indefinitely.
<computeroutput>Ena</computeroutput> tells whether the timer is
enabled. enabled. Timers that are disabled are not run. This is a nice
way to stop a timer from working, but keep it stored for later use. We
will see how to enable and disable timer later in this section. After
that, <computeroutput>Temp</computeroutput> tells whether the timer is
temporary or not. Temporary timers were explained in the previous
section. In brief, a temporary timer is deleted (and not only
disabled) after its count reaches zero. The last column shows the
action associated with the timer.</para>

<para>The listing produced by <function>$world-&gt;listtimer</function>
is compact, showing all timers but possibly truncating the action. If
you give a timer number as argument to <function>listtimer</function>,
it will display that timer's information detailedly.</para>

<para>To edit a timer, you need to know that timer's number. (And
that can be discovered with the listing functions just described.) The
same function used to add timers can also change existing ones, you
just need to pass the timer number as the first argument.</para>

<para>The generay way to edit a timer is like this:
<userinput>$world-&gt;timer(<replaceable>number</replaceable>, {
<replaceable>new attributes</replaceable> })</userinput>, where
<replaceable>new attributes</replaceable> is a list of the attributes
you want to change. For example, the code below changes the interval
of timer number two:</para>

<example><title>Changing the interval of a timer</title>
<programlisting>
$world-&gt;timer(2, { interval =&gt; 30 })
</programlisting>
</example>

<para>As a further example, consider the one below, that edits timer
number five to be temporary and to run 10 times:</para>

<example><title>Changing the interval of a timer</title>
<programlisting>
$world-&gt;timer(5, { temporary =&gt; 1,
                   count =&gt; 10 })
</programlisting>
</example>

<para>It is possible to enable and disable timers with the syntax
above, but there is a shorter way: the
<function>$world-&gt;distimer</function> function disables the timer
whose number is passed as argument, as shown in the example
below:</para>

<example><title>Disabling a timer, the short way</title>
<programlisting>
$world-&gt;distimer(3)
</programlisting>
</example>

<para>The corresponding function <function>$world-&gt;enatimer</function>
enables the specified timer.</para>

<para>It is also possible to temporarily disable all timers. Just use
the menu
<menuchoice>
  <guimenu>Preferences</guimenu>
  <guimenuitem>Disable Timers</guimenuitem>
</menuchoice>
and this will prevent timers from running. This does not change the
"enabled" status of any timers, it just prevents all timers from
running. When you select the menu again, timers that were enabled will
run again, and those that were disabled will remain disabled.</para>

<para>There are times when you want to delete a timer. This is easy to
do, use the <function>$world-&gt;deltimer</function> function. It takes
as argument the number of the timer you wish to delete. Be aware that
once deleted it is not possible to recover the timer (unless you
create it again). Many times just disabling it is a better idea. The
second thing to note is that when you delete a timer the numbers of
the other timers may change, so be careful when you try to delete
several timers in sequence.</para>

</sect2>


<sect2><title>Assigning Names to Timers</title>

<para>It is possible to assign names to timers. When a timer has a
name, you can enable, disable, or delete it using its name instead of
its number.</para>

<para>To assign a name to a timer, specify the <literal>name</literal>
attribute when creating it:</para>

<example><title>Creating a timer with a name</title>
<programlisting>
$world-&gt;timer({ interval =&gt; 60,
                action =&gt; 'who',
                name =&gt; 'who' })
</programlisting>
</example>

<para>You can now disable this timer with
<userinput>$world-&gt;distimer('who')</userinput>. The name can also be
used in the <function>$world-&gt;enatimer</function>,
<function>$world-&gt;deltimer</function> and
<function>$world-&gt;listtimer</function> functions.</para>

<para>It is also possible to assign a name to an existing timer. Just
edit it as described in <xref linkend="sec:edit_timer_cmdline"/>,
passing the <literal>name</literal> attribute. Use this same process
to change the name of a timer.</para>

<para>Another feature of timer names is that several timers can have
the same name. In this case, all these timers will be treated as a
single group. The functions above, when passed a timer name, will act
upon all timers of the group, that is, on all timers with that
name.</para>

</sect2>


<sect2><title>Reordering Timers</title>

<para>It is possible to move a timer to another position with the
<function>$world-&gt;movetimer</function> function.</para>

<para>The function takes two parameters: the first is the name or
number of the timer that you want to move. The second is the new
position that the timer will take in the list. 0 means move the the
first position. If you specify a negative number or a number greater
than the number of timers, the timer will be moved to the end of the
list.</para>

<para>If there are several timers with the same name, only the first
one found will be moved. And when a timer is moved, other timers might
move up or down to accomodate the change.</para>

</sect2>

</sect1>

</chapter>



<chapter id="chap:hooks"><title>Hooks</title>

<para>Hooks allow you to specify an action to be executed
automatically when some events happen. For example, you can define a
hook with actions to be executed when a connection is established, and
then these commands will be automatically executed when you connect to
the World.</para>

<para>You can connect hooks to seven events:</para>

<itemizedlist>
  <listitem><para><literal>OnConnect</literal>: This hook is executed
  when a connection to the world is made, after the auto-logon has
  taken place (if applicable).</para></listitem>

  <listitem><para><literal>OnDisconnect</literal>: This hook is executed
  when you are disconnected from a World, after the connection has
  been closed.</para></listitem>

  <listitem><para><literal>OnReceivedText</literal>: Executed when
  text is received from the world. The text received is available for
  the hook in the <varname>$hookdata</varname> variable, and can be
  inspectd in Perl scripts.</para></listitem>

  <listitem><para><literal>OnSentCommand</literal>: Executed after a
  command is sent to the world. The command is available for the hook
  in the <varname>$hookdata</varname> variable, and can be inspectd in
  Perl scripts.</para></listitem>

  <listitem><para><literal>OnGetFocus</literal>: Executed when the
  KildClient window receives the focus.</para></listitem>

  <listitem><para><literal>OnLoseFocus</literal>: Executed when the
  KildClient window loses the focus.</para></listitem>

  <listitem><para><literal>OnCloseDisconnected</literal>: Executed when the
  world is forcedly closed. This can happen using the
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Close</guimenuitem>
</menuchoice>
menu, the <function>$world-&gt;close()</function> function, or by
quitting the program with the world connected. You can put in this
hook, for example "<userinput>quit</userinput>" to always exit the MUD
nicely, even if you close the world by mistake.</para></listitem>

</itemizedlist>



<sect1><title>Creating and Editing Hooks</title>

<para>The easiest way to create and alter hooks is from the World
Editor, the place where all settings of a World are altered (see <xref
linkend="chap:world_editor"/>).</para>

<para>Hook are defined in the <guilabel>Hooks</guilabel> section
inside the <guilabel>Automation</guilabel> section. When you open that
section, you'll see a list of the defined hooks and some buttons
like this:</para>

<figure><title>The graphical Hook editor</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_hooks.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The graphical Hook editor.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>In the top there is a combo box for you to select one of the
five events described above. When an event is selected the hooks
defined for that event will be listed, and all operations will be done
on hooks of that event.</para>

<para>The main part of the window is the list of defined hooks. The
columns are as follows:</para>

<itemizedlist>
  <listitem><para><guilabel>Enabled</guilabel> specifies whether the
  hook is enabled or not. Hooks that are not enabled are not active
  and will not be run, but they remain in the list so that they can
  later be enabled again.</para></listitem>

  <listitem><para><guilabel>Name</guilabel> is a name that is assigned
  to a hook. This helps you identify the hook's purpose and is
  useful when editing a hook via the command line (as described in
  <xref linkend="sec:edit_hook_cmdline"/>). Assigning a name to a
  hook is optional.</para></listitem>

  <listitem><para><guilabel>Action</guilabel> defines what is done
  when the hook is run..</para></listitem>
</itemizedlist>


<sect2 id="sec:add_hook_gui"><title>Adding Hooks</title>

<para>To add a new hook, select the desired event from the Combo Box
and press the <guilabel>Add</guilabel> button. This will open a window
for you to edit the new hook's parameters:</para>

<figure><title>The window to edit hooks</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_hook_edit.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The window to edit hooks.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>What can be set represents the columns described above.</para>

<para>When you are finished, press <guilabel>OK</guilabel> and the
hook will be added. If you change your mind, press
<guilabel>Cancel</guilabel> and the hook will not be added.</para>

<para>To see some things hooks can do, read <xref linkend="sec:hook_cmdline"/>. If you want to try the hooks
described there, you can create them from the World Editor.</para>

</sect2>


<sect2><title>Altering Hooks</title>

<para>To edit a hook, select the event from the combo box, then select
the hook to edit in the list by clicking its line in the list (the
line will be highlighted), and press the <guilabel>Edit</guilabel>
button. A window like the one used for adding hook (see <xref
linkend="sec:add_hook_gui"/>) will be opened, filled with the hook's
parameters. Change what you want, and press the
<guilabel>OK</guilabel> to commit the changes. If, however, you change
you mind, press <guilabel>Cancel</guilabel> and the changes will be
not be made, the hook will remain as it was before.</para>

<para>Another shorter way to edit a hook is to double click its line
in the list.</para>

<para>It is also possible to change the value of enabled setting
directly from the hook list. Make sure that the hook you want to
change is selected, and click in the check button. The state will be
toggled.</para>

<para>To delete a hook, select it and press the
<guilabel>Delete</guilabel> button. You will be asked for
confirmation, and can cancel the operation, but once deleted, you
cannot recover the hook. If you want, you can disable this
confirmation dialog, but if you do so and click the
<guilabel>Delete</guilabel> button, the only way to undo your action
will be creating the hook again. See <xref
linkend="sec:we_advanced"/>. To delete several hooks at once, select
them all and press <guilabel>Delete</guilabel>.</para>

<para>The final thing that needs to be explained with regard to hooks
is how to reorder them. Hooks as run from the first one to the last,
so in a few cases the order might matter. To move a hook up or down in
the list, select it and press the corresponding button.</para>

</sect2>

</sect1>



<sect1 id="sec:hook_cmdline">
<title>Defining Hooks in the Command Line</title>

<para>For those more used to Perl and to command lines, it is also
possible to define and alter hooks from the command line. This is
done with a series of Perl function.</para>

<para>Hooks are defined with the <function>$world-&gt;hook</function>
function. This function works similarly to
<function>$world-&gt;trigger</function> (described in <xref
linkend="chap:triggers"/>).</para>

<para>The simplest way to call the function is with two arguments:
<function>$world-&gt;hook(<replaceable>event</replaceable>,
<replaceable>action</replaceable>)</function>. This defines a hook for
the given event (see above for the valid events) that does
<replaceable>action</replaceable> when the event is fired. As always,
<replaceable>action</replaceable> can be some text or a Perl
action.</para>

<para>Here's an example of connecting a hook to the
<literal>OnConnect</literal> event:</para>

<example><title>Connecting a hook</title>
<programlisting>
$world-&gt;hook('OnConnect', 'user Bob %; password 12345')
</programlisting>
</example>

<para>This hook causes the lines to the sent to the MUD when a
connection is established, supposedly representing a way to log in to
some MUD server.</para>


<sect2 id="sec:edit_hook_cmdline"><title>Editing Hooks</title>

<para>Before going into editing, let us see how to get a list of all
hooks that are currently defined for a given event. Just use the
<function>$world-&gt;listhook</function> function with the event name as
argument. You will be presented with a list of the currently defined
hooks for that event.</para>

<para>There are three columns: <computeroutput>Num</computeroutput> is
the number of the hook. Hooks are numbered sequentially starting at
zero, but keep in mind that there is a separete numbering for each
event. This number will be useful when we start editing hooks. After
that, <computeroutput>Ena</computeroutput> tells whether the hook is
enabled. Hooks that are disabled are not run. This is a nice way to
stop a hook from working, but keep it stored for later use. We will
see how to enable and disable hook later in this section. The last
column shows the action of the hook.</para>

<para>The listing produced by <function>$world-&gt;listhook</function>
is compact, showing all hooks but possibly truncating the pattern
and/or substitution. If you give a hook number or name as the second
argument to <function>listhook</function> (the first argument is the
event, as always), it will display that hook's information
detailedly.</para>

<para>To edit a hook, you need to know that hook's number. (And that
can be discovered with the listing functions just described.) The same
function used to add hooks can also change existing ones, you just
need to pass the hook number as the second argument.</para>

<para>Calling
<function>$world-&gt;hook(<replaceable>event</replaceable>,
<replaceable>number</replaceable>, <replaceable>new
action</replaceable>)</function> changes the action of the hook with
that number for that event.</para>

<para>The only attribute for hooks, besides the action is
<literal>enabled</literal>. It was mentioned briefly when we described
how to list hooks. It can be set just like the other attributes and is
<emphasis>binary</emphasis>, that is, takes the values
<emphasis>true</emphasis> (represented by anything different from 0)
or <emphasis>false</emphasis> (represented by 0). When the value of
this attribute is true (which is the default), the hook is tried
normally. When it is zero, commands are not tried against it. This
way, disabling a hook effectively turns if off, as if it did not
exist, but the hook is still saved, and can be turned on again when
necessary.</para>

<para>Here's an example of disabling a hook (number 0 of event
<literal>OnConnect</literal> in this case):</para>

<example><title>Disabling a hook, the long way</title>
<programlisting>
$world-&gt;hook('OnConnect', 0,
             { enabled =&gt; 0 })
</programlisting>
</example>

<para>However, there is a shorter way: the
<function>$world-&gt;dishook</function> function. It takes two
arguments: the event and the hook number, and disables the hook with
the given number. So the example above can be rewritten in a shorter
way as:</para>

<example><title>Disabling a hook, the short way</title>
<programlisting>
$world-&gt;dishook('OnConnect', 0)
</programlisting>
</example>

<para>The corresponding function <function>$world-&gt;enahook</function>
enables the specified hook.</para>

<para>There are times when you want to delete a hook. This is easy to
do, use the <function>$world-&gt;delhook</function> function. It takes as
argument the event and the number of the hook wish to delete. Be aware
that once deleted it is not possible to recover the hook (unless you
create it again). Many times just disabling the hook is a better idea.
The second thing to note is that when you delete a hook the numbers of
the other hook may change, so be careful when you try to delete
several hooks in sequence.</para>

</sect2>


<sect2><title>Assigning Names to Hooks</title>

<para>It is possible to assign names to hook. When a hook has a name,
you can enable, disable, or delete it using its name instead of its
number.</para>

<para>To assign a name to a hook, specify the <literal>name</literal>
attribute when creating it:</para>

<example><title>Creating a hook with a name</title>
<programlisting>
$world-&gt;hook('OnConnect', 'user Bob %; password 12345',
             { name =&gt; 'connection' })
</programlisting>
</example>

<para>You can now disable this hook with
<userinput>$world-&gt;dishook('OnConnect', 'connection')</userinput>.
The name can also be used in the
<function>$world-&gt;enahook</function>,
<function>$world-&gt;delhook</function> and
<function>$world-&gt;listhook</function> functions.</para>

<para>It is also possible to assign a name to an existing hook. Just
edit it as described in <xref linkend="sec:edit_hook_cmdline"/>,
passing the <literal>name</literal> attribute. Use this same process
to change the name of a hook.</para>

<para>Another feature of hook names is that several hooks can have the
same name. In this case, all these hooks will be treated as a single
group. The functions above, when passed a hook name, will act upon all
hooks of the group, that is, on all hooks with that name.</para>

</sect2>

</sect1>

</chapter>



<chapter id="chap:plugins"><title>Plugins</title>

<para>Plugins extend the functionality of KildClient. They add more
features that make the client even more powerful.</para>

<para>Basically, plugins can define triggers, aliases, macros and
timers and/or new functions. Whenever the plugin is loaded, the new
functionality is available.</para>

<para>You can work with plugins from the World Editor (see <xref
linkend="chap:world_editor"/>). Open the World Editor, and select the
<guilabel>Plugins</guilabel> section inside
<guilabel>Automation</guilabel>. You will see a screen like
this:</para>

<figure><title>The Plugin list</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/we_plugins.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Plugin list.</phrase>
    </textobject>
  </mediaobject>
</figure>

<para>There are two lists in the window: one lists the plugins that
are currently loaded and that can be used. The other lists the plugins
in the startup list, which are plugins that are loaded automatically
for you whenever you connect to the World.</para>

<para>To load a plugin, press the <guilabel>Load</guilabel> button. A
dialog will be opened for you to select the file. Select the file and
press <guilabel>Open</guilabel>. The plugin will be loaded and will
appear in the list. Or, if there was a problem and the plugin could
not be loaded, the reason will be given in a message box.</para>

<para>While selecting the file, you have the option to specify that
the plugin is to be loaded always at startup (that is, when you
connect to the World). If you select that option, the plugin will also
be added to the other list.</para>

<para>You can get help for a loaded plugin by selecting its line and
pressing the <guilabel>Help</guilabel> button. Some help describing
how to use the plugin will be shown in the main World window.</para>

<para>You can disable a plugin that is loaded. When a plugin is
disabled, it is turned off temporarily. To disable a plugin, select
its line in the list of loaded plugins and click the check box in the
<guilabel>Enabled</guilabel> column. To enable it back, click in the
check box again.</para>

<para>To add a plugin that is to be loaded always at startup (without
loading it now, or if it is already loaded), press the
<guilabel>Add</guilabel> button after the list of the startup plugins.
A dialog box will open for you to select the file, and if that file
could be loaded, the plugin will be added to the list.</para>

<para>To remove a plugin so that it is not loaded anymore at startup,
select its line and press <guilabel>Remove</guilabel>. And to change
the order that the plugins are loaded, select the line and use the
<guilabel>Up</guilabel> and <guilabel>Down</guilabel> buttons to move
the plugin.</para>



<sect1><title>Loading Plugins from the Command Line</title>

<para>It is also possible to load plugins directly from the command
line, for those more comfortable with it and with Perl.</para>

<para>To load a plugin, the <function>$world-&gt;loadplugin</function>
function is used. It must be called with one argument, which can be
either the full path to the file that defines the plugin, or just the
plugin name. But for this to work, the file must be installed in one
of the directories that KildClient looks for plugins. By default, two
locations are searched for: one is the <filename
class="directory">plugins</filename> directory under KildClient's
directory in your HOME path (that is, <filename
class="directory">~/.kildclient/plugins</filename> in UNIX systems).
The other is the <filename role="directory">plugins</filename>
directory under the directory where KildClient stores some of its
files (generally it is something like <filename
class="directory">/usr/local/share/kildclient/plugins</filename>).</para>

<para>For example, here is how to load the <literal>keypad</literal>
plugin (which is a standard plugin distributed with
KildClient):</para>

<example><title>Loading a plugin</title>
<programlisting>
$world-&gt;loadplugin('keypad')
</programlisting>
</example>

<para>As an additional example, the code below loads a plugin
specifying its full filename:</para>

<example><title>Loading a plugin specifying the full filename</title>
<programlisting>
$world-&gt;loadplugin('/home/joe/kildclient-plugins/attackplugin.pl')
</programlisting>
</example>

<para>Either way, you should see a message saying that the plugin has
been loaded. It is now already working. If the plugin was already
loaded, loading will fail.</para>

<para>To always load the plugin when you connect to the World, either
use the World Editor as described above, or add the line that loads it
to your script file. See <xref linkend="sec:we_scripting"/>.</para>


<sect2><title>Enabling and Disabling Plugins</title>

<para>If you want to turn off a plugin temporarily, you can disable
it. Later, when you want it to work again, just reenable it.</para>

<para>To disable a plugin, use the
<function>$world-&gt;displugin</function> function, passing as argument
the name of the plugin. What this function does is disable the
plugin's triggers, aliases, macros and timers. You can still call the
plugin functions directly.</para>

<para>To enable a plugin again, use the
<function>$world-&gt;enaplugin</function> function, passing as argument
the name of the plugin.</para>

</sect2>

</sect1>


<sect1><title>Getting Information About Plugins</title>

<para>All plugins should contain a <function>help</function> function
that, when called, prints information about the plugin. If you want to
get help on a plugin, call its <function>help</function> function. The
example below shows how to call the <function>help</function> of the
<literal>keypad</literal> plugin:</para>

<example><title>Getting help about a plugin</title>
<programlisting>
keypad::help()
</programlisting>
</example>

<para>Note that the name of the function is prefixed with the name of
the plugin and <literal>::</literal>. This is a convention so that one
plugin's functions do not interfere with other plugins' ones.</para>

<para>It is possible to get a list of all the currently loaded plugins
with the <function>$world-&gt;listplugin</function> function. If called
without arguments, it lists briefly all loaded plugins. But you can
pass as argument either a plugin number or a plugin name, and it will
give more detailed information about that plugin, including a listing
of the triggers, aliases, macros and timers that the plugin defines
(if any).</para>

</sect1>


<sect1><title>Standard Plugins</title>

<para>KildClient comes with a few plugins as part of its distribution.
These plugins will be described here. You can load these plugins as
described above.</para>


<sect2 id="plugin:easypath"><title>easypath</title>

<para>This plugin makes the use of paths (see <xref
linkend="sec:paths"/>) easier. When this plugin is loaded, you can
type <userinput>#2n3e{sw}</userinput> instead of
<userinput>/path("2n3e{sw}")</userinput>.</para>

</sect2>


<sect2 id="plugin:keypad"><title>keypad</title>

<para>This plugin allows use of the keypad for movement. Pressing the
left arrow of the numeric keypad moves to the east, pressing the up
arrow moves to the north, and so on.</para>

<para>A few other keys of the keypad are also bound:
<keysym>-</keysym> and <keysym>+</keysym> represent down and up,
respectively. <keysym>5</keysym> sends <literal>who</literal>,
<keysym>0</keysym> sends <literal>look</literal>, <keysym>/</keysym>
sends <literal>inventory</literal> and <keysym>*</keysym> sends
<literal>score</literal>.</para>

<para>The <keysym>Num Lock</keysym> key must be off for this plugin to
work.</para>

</sect2>


<sect2 id="plugin:notes"><title>notes</title>

<para>This plugin allows you to assign notes to World. The notes are
saved with the World and are restored when it is opened again. You can
write anything you want, probably it will be something you want to
remember for that World.</para>

<para>This plugin requires the gtk2-perl bindings, because it has a
graphical user interface.</para>

<para>Type <userinput>/notes::edit</userinput> to open a window where
you can edit the notes. When you are finished, press the
<guilabel>Close</guilabel> button. The notes are saved
automatically.</para>

<para>Use the <function>notes::clear</function> function to clear the
whole contents of the notes.</para>

<para>It is  also possible to append something to the notes with
<function>notes::append('text')</function>. This is probably more
useful in scripts.</para>

</sect2>


<sect2 id="plugin:kc256"><title>kc256</title>

<para>This plugin demonstrates a useful extension to the 16 ansi
colors that KildClient supports. This is the same 256-color extension
supported by xterm (if it is complied with support for that).</para>

<para>With this extension, you can specify any color in a 6x6x6 RGB
color cube, that is, you have 216 rgb colors at your disposal, plus 24
shades of gray. (The remaining 16 colors are the standard ansi
colors.)</para>

<para>There are two functions in this plugin:</para>

<para><function>kc256::showcolors</function>: Displays all 216
available RGB colors and the 24 shades of grey in nice tables, with
the values that you can use in <xref linkend="func:colorize"
endterm="func:colorize.title"/> to access them.</para>

<para><function>kc256::rainbowtext(<parameter>$string</parameter>)</function>:
Just a demonstration on how (not to) use the colors. Displays
<parameter>$string</parameter>, one character in a different
color.</para>

</sect2>


<sect2><title>Other Plugins</title>

<para>The <literal>KCWin</literal> plugin allows you to create general
purpose windows a terminal for output and an entry box for input.
These windows do nothing by themselves, but they can be used by other
plugins when they need a window for input and output.</para>

<para>Since this plugin is just a helper for other plugins, it is not
described here, but rather in <xref linkend="app:KCWin"/>.</para>

<para>The <literal>chat</literal> plugin allows peer to peer chat with
other users of KildClient and of other clients that support the
MudMaster or zChat protocols. It is described in its own chapter,
<xref linkend="chap:chat"/>.</para>

</sect2>

</sect1>

</chapter>



<chapter id="chap:logging"><title>Logging the Output</title>

<para>A useful feature of KildClient is it hability to log all the
output from the MUD, as shown in the screen, so that you can retrieve
it later.</para>

<para>The output is saved in a file you specify. ANSI color codes are
not saved, but otherwise the output is identical.</para>

<para>It is possible to prefix each line with a timestamp, so you can
see when each line was received. You can specify the format of this
timestamp.</para>

<para>Logging is controlled with the
<function>$world-&gt;logfile</function> function. The first argument
specifies the path to the file where the output is saved. If the file
already exists, new text will be appended to it.</para>

<para>The second argument, if present, controls the format of the
timestamp. If you do not want a timestamp, then do not pass a second
argument, pass only the file name. This timestamp argument is a string
with control codes. Each control code will be substituted by a part of
the time or date. This sequences are the ones of the
<function>strftime()</function> C function, so see its man page for
the list of control sequences.</para>

<para>Here's an example that turns on logging, with a timestamp that
shows the date and time:</para>

<example><title>Enabling logging</title>
<programlisting>
$world-&gt;logfile('/home/bob/mud/mudlog.txt', '%b/%d %H:%M:%S&gt; ')
</programlisting>
</example>

<para>To turn off logging, just call <function>logfile</function> with
no arguments.</para>

<para>There are functions to write arbitrary text to the log file:
<xref linkend="func:writetolog" endterm="func:writetolog.title"/> and
<xref linkend="func:echonlandlog"
endterm="func:echonlandlog.title"/>.</para>

</chapter>



<chapter id="chap:chat"><title>Using the Chat</title>

<para>KildClient supports peer to peer chat (that is, you talk
directly to the other person, and not via a server, be it a MUD server
or a chat server), which allows you to talk to other users of
KildClient or other clients that support the MudMaster or zChat
protocols (both are supported by KildClient).</para>

<para>There are several advantages of chatting directly with the other
person:</para>

<itemizedlist>
<listitem><para>You can chat even if the MUD is down, since the MUD server
is not involved.</para></listitem>

<listitem><para>Since the chat is direct, it cannot be snooped by
immortals or administrators.</para></listitem>

<listitem><para>The chat is independent from the MUD, so you can chat
even if you in a situation in which it would not be possible to talk
through the MUD.</para></listitem>
</itemizedlist>

<para>The chat also supports other features that are not possible
through a MUD, such as snooping a session, that is, seeing everything
the other player sees in the screen (if they allow you to do so, of
course), or sending everything you see to your chat party (if you
allow that, of course), or transfering files.</para>

<para>These features do not pose a security risk, because they can be
disabled and the other person can only see your output if you allow
it, and they can only send files if you allow them to.</para>


<sect1><title>Basic Usage</title>

<para>The chat plugin requires the Gtk2 Perl bindings, and also the
Perl bindings for the vte library. If you cannot load the plugin and
it complains about not finding these bindings, go to <ulink
url="http://http://gtk2-perl.sourceforge.net/">http://gtk2-perl.sourceforge.net/</ulink>
and download them.</para>

<para>To load the plugin, enter
<userinput>/$world-&gt;loadplugin('chat')</userinput> in the command
entry box. You should see <literal>Plugin loaded</literal>. If an
error happened, you probably do not have the bindings mentioned in the
above paragraph.</para>

<para>If you want to have the plugin always loaded, you can put that
line (without the slash in the beginning) to your script file, and the
plugin will loaded whenever you open a World.</para>

<para>Now that the plugin is loaded, you have two options: calling
somebody or accepting calls from other persons.</para>

<para>The first thing you should do is set you chat nickname. To do
that, type <userinput>/chat::setname("nickname")</userinput>. You only
need to do this once, as the chat name will be saved and restored when
you open the World again.</para>

<para>To accept calls, enter <userinput>/chat::accept</userinput> in
the command entry box. Other people can now call you. You will need to
give them your IP address. Calls are being waited on port 4050, which
is the default port for the chat protocols. If you want to listen for
connections in another port, just pass that port number as argument,
for example, <userinput>/chat::accept(5000)</userinput>. Be sure to
inform other people the port you are using.</para>

<para>When somebody wants to chat to you, a dialog box will appear
asking if you want to accept the chat. If you want to chat with them,
select <guilabel>Yes</guilabel> to establish the chat connection,
otherwise click <guilabel>No</guilabel> to deny the chat
request.</para>

<para>To call somebody, use the <function>call</function> function:
enter <userinput>/chat::call("host")</userinput>.
<parameter>host</parameter> is the hostname or IP address of the
person you wish to chat with. This command tries connecting to port
4050, if they are using another port, pass that port number as a
second argument to the function.</para>

<para>You can substitute <function>call</function> for
<function>zcall</function>. The later tries using the zChat protocol
instead of the default MudMaster protocol. Use the
<function>zcall</function> function if you know they support the zChat
protocol.</para>

<para>If the other person accepts the chat, the connection will be
established.</para>

<para>Each chat connection has its own window where the text received
is displayed, and with an entry box where you can type messages that
are sent to the other person. To send something, just enter the
message and press <keysym>ENTER</keysym>.</para>

<para>There are some special commands that can be entered in chat windows,
these will be described in the next session.</para>

</sect1>


<sect1><title>Advanced Features</title>

<para>There are other things you can do besides simply chatting. These
functions are accessed by typing some commands in the chat window.
These commands start with <literal>/</literal>, but do not confuse
them with the usage of <literal>/</literal> in the main KildClient
window to run Perl commands.</para>

<para>Here are the commands and their actions:</para>

<variablelist>
<varlistentry><term>/emote <replaceable>text</replaceable></term>
<listitem><para>Sends <replaceable>text</replaceable> as an emote and
not as a chat message, that is, sends a message in the form
<emphasis>name text</emphasis>.</para></listitem>
</varlistentry>

<varlistentry><term>/chatall <replaceable>text</replaceable></term>
<listitem><para>Sends <replaceable>text</replaceable> to all chat
connections.</para></listitem>
</varlistentry>

<varlistentry><term>/emoteall <replaceable>text</replaceable></term>
<listitem><para>Sends <replaceable>text</replaceable> as an emote to
all chat connections.</para></listitem>
</varlistentry>

<varlistentry><term>/group <replaceable>group name</replaceable></term>
<listitem><para>Makes this chat connection a member of the specified
group.</para></listitem>
</varlistentry>

<varlistentry><term>/cg <replaceable>text</replaceable></term>
<listitem><para>Sends <replaceable>text</replaceable> to all
connections that are members of the group that this chat session
belongs.</para></listitem>
</varlistentry>

<varlistentry><term>/eg <replaceable>text</replaceable></term>
<listitem><para>Sends <replaceable>text</replaceable> as an emote to
all connections that are members of the group that this chat session
belongs.</para></listitem>
</varlistentry>

<varlistentry><term>/name <replaceable>nickname</replaceable></term>
<listitem><para>Changes the chat nickname to the one given. This
affects all chat sessions.</para></listitem>
</varlistentry>

<varlistentry><term>/color <replaceable>code</replaceable></term>
<listitem><para>Changes the color used in this chat session to the one
specified. <replaceable>code</replaceable> is a color code as
recognized by the <xref linkend="func:colorize"
endterm="func:colorize.title"/> function. Note that this affects only
chat messages and the text you send, if the chat peer sends messages
in another color, they will be displayed in the color the peer chose.
This affects all chat sessions.</para></listitem>
</varlistentry>

<varlistentry><term>/stripansi</term>
<listitem><para>Strips ANSI color codes in messages received in this
chat. That means that colors sent by the peer will not be displayed,
and that even incoming messages will be displayed in your chat
color.</para></listitem>
</varlistentry>

<varlistentry><term>/nostripansi</term>
<listitem><para>Does not strip ANSI color codes in messages received
in this chat. That means that colors sent by the peer will be
displayed.</para></listitem>
</varlistentry>

<varlistentry><term>/ping</term>
<listitem><para>Pings the other peer. If the connection is alive, they
will reply to this request. Additionally, the time for the reply to be
received is displayed.</para></listitem>
</varlistentry>

<varlistentry><term>/sendfile</term>
<listitem><para>Attemps to send a file to the peer. A dialog will be
displayed for you to select the file to send, and the file will be
offered. If they accept, the file transfer will
start.</para></listitem>
</varlistentry>

<varlistentry><term>/stopfile</term>
<listitem><para>Stops the file transfer currently in
progress.</para></listitem>
</varlistentry>

<varlistentry><term>/snoop</term>
<listitem><para>Asks the peer if you can snoop them, that is, see
everything they see in their MUD session. If they accept, everything
they see will be sent to you and displayed.</para></listitem>
</varlistentry>

<varlistentry><term>/allowsnoop</term>
<listitem><para>Allows the peer to snoop you, that is, they can see
everything you see in your MUD session. Be careful with this command.
By default snooping is not allowed to protect your
privacy.</para></listitem>
</varlistentry>

<varlistentry><term>/noallowsnoop</term>
<listitem><para>Disallows the peer to snoop you, that is, they cannot
see what you see in your MUD session. By default snooping is disabled,
and this command is used to disable it again if you had enabled
it.</para></listitem>
</varlistentry>

<varlistentry><term>/info</term>
<listitem><para>Shows some information about the chat
session.</para></listitem>
</varlistentry>

<varlistentry><term>/hangup</term>
<listitem><para>Stops this chat session. You will need to connect
again to continue talking.</para></listitem>
</varlistentry>
</variablelist>

<para>As you can see, the chat offers much more than simply chatting.
One of its features is file transfer. To send a file, use the
/sendfile command, as descrived above. When your peer wants to send
you a file, a dialog box will be displayed telling you the name and
size of the file. If you want the file, select
<guilabel>Yes</guilabel> and another dialog will be displayed for you
to you can select where to store the file. The file transfer will then
begin. Or you can refuse the file by clicking <guilabel>No</guilabel>.
You can interrupt a file transfer in progress by using the /stopfile
command.</para>

<para>By default, you are prompted whenever somebody wants to talk
with you. If you want to avoid this question and automatically accept
all chats, set the <varname>$chat::auto_accept_calls</varname>
variable to 1 (that is, enter something like
<userinput>/$chat::auto_accept_calls = 1</userinput>). This setting
will be remembered. Set it to 0 to have the prompts again.</para>

<para>If, however, you do not want to chat with anyone, the best thing
is to disable accepting connections. Just type
<userinput>/chat::noaccept</userinput>. Use
<userinput>/chat::acceptcalls</userinput> to accept calls
again.</para>

</sect1>


<sect1><title>Chat Functions</title>

<para>You can also access the chat features via some Perl functions of
the chat plugin. Here is a list of these functions:</para>

<variablelist>
<varlistentry><term><function>chat::call(<parameter>host</parameter>, [<parameter>port</parameter>])</function></term>

<listitem><para>Tries connection to <parameter>host</parameter>, on
port <parameter>port</parameter> (or 4050, if not specified), using
the MudMaster protocol.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::zcall(<parameter>host</parameter>, [<parameter>port</parameter>])</function></term>

<listitem><para>Tries connection to <parameter>host</parameter>, on
port <parameter>port</parameter> (or 4050, if not specified), using
the zChat protocol.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::accept([<parameter>port</parameter>])</function></term>

<listitem><para>Starts listening for chat connections on the given
port (or 4050 if not specified).</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::noaccept()</function></term>

<listitem><para>Stops listening for chat
connections.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::setname(<parameter>nickname</parameter>)</function></term>

<listitem><para>Sets the nickname used in chat
sessions.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::setcolor(<parameter>code</parameter>)</function></term>

<listitem><para>Sets the color used in chat sessions.
<parameter>code</parameter> is a color code as recognized by the <xref linkend="func:colorize" endterm="func:colorize.title"/>
function</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::chat(<parameter>name</parameter>, <parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> to
<parameter>name</parameter>.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::emote(<parameter>name</parameter>, <parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> as an emote to
<parameter>name</parameter>.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::chatall(<parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> to all chat
connections.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::emoteall(<parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> as an emote to all
chat connections.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::group(<parameter>name</parameter>, <parameter>group</parameter>)</function></term>

<listitem><para>Makes the chat connection with
<parameter>name</parameter> a member of the group
<parameter>group</parameter>.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::chatgroup(<parameter>group</parameter>, <parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> to all connections
that are members of the group
<parameter>group</parameter>.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::emotegroup(<parameter>group</parameter>, <parameter>text</parameter>)</function></term>

<listitem><para>Sends <parameter>text</parameter> as an emote to all
connections that are members of the group
<parameter>group</parameter>.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::ping(<parameter>name</parameter>)</function></term>

<listitem><para>Pings the other peer. If the connection is alive, they
will reply to this request. Additionally, the time for the reply to be
received is displayed.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::sendfile(<parameter>name</parameter>, [<parameter>file</parameter>])</function></term>

<listitem><para>Attemps to send a file to the peer. If you do not
specify the file, a dialog will be displayed for you to select the
file to send. The file will be offered. If they accept, the file
transfer will start.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::stopfile(<parameter>name</parameter>)</function></term>

<listitem><para>Stops the file transfer currently in
progress.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::snoop(<parameter>name</parameter>)</function></term>

<listitem><para>Asks <parameter>name</parameter> if you can snoop
them, that is, see everything they see in their MUD session. If they
accept, everything they see will be sent to you and
displayed.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::setallowsnoop(<parameter>name</parameter>, <parameter>value</parameter>)</function></term>

<listitem><para>Sets whether <parameter>name</parameter> can snoop you,
that is, wheter they can see everything you see in your MUD session,
according to <parameter>value</parameter>. By default snooping is
disabled.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::info(<parameter>name</parameter>)</function></term>

<listitem><para>Shows some information about the chat
session.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::setstripansi(<parameter>name</parameter>, <parameter>value</parameter>)</function></term>

<listitem><para>Sets whether to trip ANSI color codes in messages
received from <parameter>name</parameter>, according to
<parameter>value</parameter>. If they are, colors sent by the peer
will not be displayed, and that even incoming messages will be
displayed in your chat color.</para></listitem>
</varlistentry>


<varlistentry><term><function>chat::hangup(<parameter>name</parameter>)</function></term>

<listitem><para>Stops the chat session with
<parameter>name</parameter>. You will need to connect again to
continue talking.</para></listitem>
</varlistentry>
</variablelist>

</sect1>

</chapter>

</part>




<part><title>KildClient Programmer's Reference</title>


<appendix id="app:functions"><title>Global Function Reference</title>

<sect1 id="func:colorize">
<title id="func:colorize.title"><function>colorize</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$color = <function>colorize</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Replaces color codes (see below) in the string with ANSI escape
sequences,so that the string can be echoed in the terminal, for
example. Returns the colorized string.</para>

<para>Color code table (based on colors used by the Smaug
server):</para>

<screen>
  &amp;0 (number zero) - Reset all attributes and colors to default
Normal colors:
  &amp;x - Black                     &amp;r - Red
  &amp;g - Green                     &amp;O - Yellow
  &amp;b - Blue                      &amp;p - Magenta
  &amp;c - Cyan                      &amp;w - White
  &amp;d - Default foreground
Bold colors:
  &amp;z - Bold Black                &amp;R - Bold Red
  &amp;G - Bold Green                &amp;Y - Bold Yellow
  &amp;B - Bold Blue                 &amp;P - Bold Magenta
  &amp;C - Bold Cyan                 &amp;W - Bold White
  &amp;D - Default bold foreground
Background colors:
  ^x - Black                     ^r - Red
  ^g - Green                     ^O - Yellow
  ^b - Blue                      ^p - Magenta
  ^c - Cyan                      ^w - White
  ^d - Default background
Light background colors (sometimes causes blinking):
  ^z - Light Black               ^R - Light Red
  ^G - Light Green               ^Y - Light Yellow
  ^B - Light Blue                ^P - Light Magenta
  ^C - Light Cyan                ^W - Light White
  ^D - Default light background
Attributes: (may not work on other clients)
  &amp;_ - Underline on              ^_ - All underline off
  &amp;= - Double underline on
  &amp;| - Strikethrough on          ^| - Strikethrough off
  &amp;/ - Italics on                ^/ - Italics off
  &amp;i - Inverse video on          ^i - Inverse video off
  &amp;h - Hidden mode on            ^h - Hidden mode off
</screen>

<para><emphasis>Note</emphasis>: if you want to set both the
foreground and the background, the code for the foreground should come
first. If you want to set the foreground and/or background and one or
more attributes (underline, italics, etc), the attribute settings
should come after the color.</para>

<para><emphasis>Note</emphasis> : to insert a &amp; or ^ character,
use &amp;&amp; and ^^, respectively.</para>

<para>You can also also use <function>colorize()</function> to display
text in any color of a 6x6x6 RGB color cube. To do so, use
<literal>&amp;<parameter>r</parameter><parameter>g</parameter><parameter>b</parameter>X</literal>
and ^rgbX to set the foreground and background, respectively.
<parameter>r</parameter>, <parameter>g</parameter>, and
<parameter>b</parameter> are integers between 0 and 5 representing the
amount of red, green and blue. X is really the letter X, it is used to
close the code.</para>

<para>Finally, to select one of the 24 shades of gray available, use
<literal>&amp;<parameter>n</parameter>G</literal> and
<literal>^<parameter>n</parameter>G</literal> for the foreground and
background, respectively, where <parameter>n</parameter> is an integer
from 0 to 23, and G is really the letter G.</para>

<para>You can use the kc256 (see <xref linkend="plugin:kc256"/>)
plugin to display all the colors for you to choose from.</para>

</sect1>


<sect1 id="func:getversion">
<title id="func:getversion.title"><function>getversion</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$version = <function>getversion</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This functions returns the version number of KildClient.</para>

</sect1>


<sect1 id="func:getwindowsize">
<title id="func:getwindowsize.title"><function>getwindowsize</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>($lines, $columns) = <function>getwindowsize</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>$columns = <function>getwindowsize</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This functions returns the current size of the window (in
characters), in terms of lines and columns. It can return both
dimensions, or just the number of columns.</para>

</sect1>


<sect1 id="func:getworld">
<title id="func:getworld.title"><function>getworld</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$var = <function>getworld</function></funcdef>
    <paramdef>
      <parameter>"name"</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Returns a variable that points to the open world with the given
name. You can then manipulate that world with the returned variable
(by calling functions that operate on worlds with that variable).</para>

<para>For example:</para>

<example id="ex:remote_quit"><title>Quitting from another
world</title>
<programlisting>
$coolmud = getworld("CoolMud");
$coolmud-&gt;send("quit");
</programlisting>
</example>

<para>This will send "<userinput>quit</userinput>" to the CoolMud
world.</para>

</sect1>


<sect1 id="func:gotow">
<title id="func:gotow.title"><function>gotow</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>gotow</function></funcdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>gotow</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Focuses the Nth world (when called with a number) or the world
with the given name (when called with a string). The first world is
numbered 0.</para>

</sect1>


<sect1 id="func:help">
<title id="func:help.title"><function>help</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>help</function></funcdef>
    <paramdef>
      <parameter>"function"</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Displays help for the given function. The name of the function
is passed as a string, so it must be in quotes.</para>

</sect1>


<sect1 id="func:minimize">
<title id="func:minimize.title"><function>minimize</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>minimize</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function minimized KildClient's main window. Called from a
macro, it makes a nice boss key. :-)</para>

</sect1>


<sect1 id="func:path">
<title id="func:path.title"><function>path</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>path</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>str is a string defining a path. The following example shows
the features of paths:</para>

<screen>
  3n2e4n2e{ne}e{open door}3n
</screen>

<para>The general syntax syntax is "<literal>&lt;number of
repetitions&gt;&lt;command&gt;</literal>". "<literal>&lt;number of
repetitions&gt;</literal>" can be omitted, in this case it is considered
as 1. <literal>command</literal> is the command that will be repeated.
If it is not a one-letter command, it should be enclosed in braces
(<literal>{}</literal>).</para>

<para>The example above would generate these commands:</para>

<screen>
  n
  n
  n
  e
  e
  n
  n
  n
  n
  e
  e
  ne
  e
  open door
  n
  n
  n
</screen>

</sect1>


<sect1 id="func:play">
<title id="func:play.title"><function>play</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>play</function></funcdef>
    <paramdef>
      <parameter>file</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This function plays a sound file. The argument is the path to
the file.</para>

</sect1>


<sect1 id="func:quit">
<title id="func:quit.title"><function>quit</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>quit</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Disconnects and closes all Worlds and KildClient exits.</para>

</sect1>


<sect1 id="func:stripansi">
<title id="func:stripansi.title"><function>stripansi</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$stripped = <function>stripansi</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Returns the string stripped of any ANSI sequences that it
had.</para>

</sect1>


<sect1 id="func:stripcolorize">
<title id="func:stripcolorize.title"><function>stripcolorize</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$stripped = <function>stripcolorize</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Returns the string stripped of any sequences used by
<xref linkend="func:colorize" endterm="func:colorize.title"/> to add
color to it.</para>

</sect1>

</appendix>



<appendix><title>$world Reference</title>

<para><varname>$world</varname> is a variable that is always present
and points to the current World. It is an object of class
<classname>World</classname>, and is opaque, that is, all interaction
with it should be done via its functions, and not via its
members.</para>

<para>The sections below describe the variables and attributes
available for the <varname>$world</varname> variable.</para>


<sect1 id="var:SILENT">
<title id="var:SILENT.title"><varname>$world-&gt;{SILENT}</varname></title>

<para>If this attribute is set to a true value (such as 1), some
messages are not displayed, especifically the messages "Trigger
added", "Trigger modified", "Trigger deleted", "Trigged moved", and
the corresponding messages for the other objects: aliases, macros,
timers, hooks, permanent variables and plugins.</para>

</sect1>


<sect1 id="func:alias">
<title id="func:alias.title"><function>$world-&gt;alias</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;alias</function></funcdef>
    <paramdef>
      <parameter>pattern</parameter>
    </paramdef>
    <paramdef>
      <parameter>substitution</parameter>
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;alias</function></funcdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
    <paramdef>
      [<parameter>pattern</parameter>
    </paramdef>
    <paramdef>
      [<parameter>substitution</parameter>]]
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Creates a new alias, or edits the alias identified by number.
Entered commands will be matched against pattern (a Perl regular
expression), and if the pattern matches, the given substitution will
be applied. (In a <literal>s/pattern/substitution/</literal>
structure.)</para>

<para>Be careful that any part of the command can match. To match only
the exact string, use something like <literal>'^command$'</literal>.
To match only in the beginning of the line, use
<literal>'^command'</literal>.</para>

<para>Atributes is a reference to a hash defining attributes for
the alias. Generally the call works like this:</para>

<programlisting>
$world-&gt;alias("pattern", "action", { attribute1 =&gt; value1,
                                     attribute2 =&gt; value2, ... })
</programlisting>

<para>Possible attributes:</para>

<itemizedlist>
  <listitem><para><literal>pattern</literal>: The pattern to
  match.</para></listitem>

  <listitem><para><literal>substitution</literal>: The substitution to
  do.</para></listitem>

  <listitem><para><literal>ignorecase</literal>: If value evaluates to
  true, ignore case when matching the pattern.</para></listitem>

  <listitem><para><literal>perleval</literal>: If true, the
  substitution is made passing the "e" flag
  (<literal>s/pattern/substitution/e</literal>), so substitution
  should be actually Perl statements to be evaluated when there is a
  match.</para></listitem>

  <listitem><para><literal>enabled</literal>: If value evaluates to
  true, the alias is enabled, if false, it is disabled and commands
  are not matched against it.</para></listitem>

  <listitem><para><literal>name</literal>: Assigns a name to the
  alias, so that it can be referenced by name.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="func:close">
<title id="func:close.title"><function>$world-&gt;close</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;close</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Disconnects and closes the current world, immediately.</para>

</sect1>


<sect1 id="func:aliasenabled">
<title id="func:aliasenabled.title">
  <function>$world-&gt;aliasenabled</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>result = <function>$world-&gt;aliasenabled</function></funcdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions checks whether the specified alias exists and
whether it is enabled.</para>

<para>You can pass either a alias number or name. If the alias does
not exist, this function returns <literal>undef</literal>, so you can
distinguish the case of a non-existant alias from a disabled
one.</para>

<para>If the alias exists, then the function returns 0 or 1 depending
on whether it is enabled or not. If you pass a name, and there are
several aliases with the same name, it returns a list with one value
for each alias with that name, and each value is 0 or 1 depending on
the state of the alias.</para>

</sect1>


<sect1 id="func:commandecho">
<title id="func:commandecho.title">
  <function>$world-&gt;commandecho</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;commandecho</function></funcdef>
    <paramdef>
      <parameter>boolean</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>$status =
    <function>$world-&gt;commandecho</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>When used with an argument, this sets the command echo option
for the current world to the given value (which should be false to
cause commands not to be echoed or true to cause them to be
echoed). For more details of the command echo option, see <xref linkend="sec:we_misc"/></para>

<para>If called without arguments, it doesn't change the status of
that option, but returns its current value.</para>

</sect1>


<sect1 id="func:connectother">
<title id="func:connectother.title">
<function>$world-&gt;connectother</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;connectother</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function allows you to select another World to connect to,
using the same window. If you are connected, you will be first
disconnected from the current server.</para>

</sect1>


<sect1 id="func:dc">
<title id="func:dc.title"><function>$world-&gt;dc</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;dc</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Disconnects from the current world.</para>

</sect1>


<sect1 id="func:delalias">
<title id="func:delalias.title"><function>$world-&gt;delalias</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;delalias</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Deletes the alias identified by the given number or name. If
there are several aliases with the same name, deletes them all.</para>

</sect1>


<sect1 id="func:delhook">
<title id="func:delhook.title"><function>$world-&gt;delhook</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;delhook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Deletes the hook identified by the given number or name,
connected to the specified event. If there are several hooks with the
same name, deletes them all.</para>

</sect1>


<sect1 id="func:delmacro">
<title id="func:delmacro.title"><function>$world-&gt;delmacro</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;delmacro</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Deletes the macro identified by the given number or name. If
there are several macros with the same name, deletes them all.</para>

</sect1>


<sect1 id="func:deltimer">
<title id="func:deltimer.title"><function>$world-&gt;deltimer</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;deltimer</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Deletes the timer identified by the given number or name. If
there are several timers with the same name, deletes them all.</para>

</sect1>


<sect1 id="func:deltrigger">
<title id="func:deltrigger.title">
  <function>$world-&gt;deltrigger</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;deltrigger</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Deletes the trigger identified by the given number or name. If
there are several triggers with the same name, deletes them
all.</para>

</sect1>


<sect1 id="func:disalias">
<title id="func:disalias.title"><function>$world-&gt;disalias</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;disalias</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the alias identified by number or name. If there are
several aliases with the same name, disables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:dishook">
<title id="func:dishook.title"><function>$world-&gt;dishook</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;dishook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the hook identified by number or name, connected to the
given event. If there are several hooks with the same name, disables
them all. Several arguments can be passed at once.</para>

</sect1>


<sect1 id="func:dismacro">
<title id="func:dismacro.title"><function>$world-&gt;dismacro</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;dismacro</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the macro identified by number or name. If there are
several macros with the same name, disables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:displugin">
<title id="func:displugin.title"><function>$world-&gt;displugin</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;displugin</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the specified plugin.</para>

</sect1>


<sect1 id="func:distimer">
<title id="func:distimer.title"><function>$world-&gt;distimer</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;distimer</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the timer identified by number or name. If there are
several timers with the same name, disables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:distrigger">
<title id="func:distrigger.title">
  <function>$world-&gt;distrigger</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;distrigger</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Disables the trigger identified by number or name. If there are
several triggers with the same name, disables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:echo">
<title id="func:echo.title"><function>$world-&gt;echo</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;echo</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Prints the strings in the terminal window. They are not sent to
the world.</para>

<para>See also <xref linkend="func:echonl" endterm="func:echonl.title"/>, <xref linkend="func:send" endterm="func:send.title"/>.</para>

</sect1>


<sect1 id="func:echonl">
<title id="func:echonl.title"><function>$world-&gt;echonl</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;echonl</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Prints the strings in the terminal window, each followed by a
newline. They are not sent to the world.</para>

<para>See also <xref linkend="func:echo" endterm="func:echo.title"/>,
<xref linkend="func:send" endterm="func:send.title"/>.</para>

</sect1>


<sect1 id="func:echonlandlog">
<title id="func:echonlandlog.title"><function>$world-&gt;echonlandlog</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;echonlandlog</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This is a convenience function that just calls <xref linkend="func:echonl" endterm="func:echonl.title"/> and <xref linkend="func:writetolog" endterm="func:writetolog.title"/> for each
argument, thus writing the given line(s) to the screen and to the log
file.</para>

</sect1>


<sect1 id="func:enaalias">
<title id="func:enaalias.title"><function>$world-&gt;enaalias</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enaalias</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the alias identified by number or name. If there are
several aliases with the same name, enables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:enahook">
<title id="func:enahook.title"><function>$world-&gt;enahook</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enahook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the hook identified by number or name, connected to the
given event. If there are several hooks with the same name, enables
them all. Several arguments can be passed at once.</para>

</sect1>


<sect1 id="func:enamacro">
<title id="func:enamacro.title"><function>$world-&gt;enamacro</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enamacro</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the macro identified by number or name. If there are
several macros with the same name, enables them all. Several arguments
can be passed at once.</para>

</sect1>


<sect1 id="func:enaplugin">
<title id="func:enaplugin.title"><function>$world-&gt;enaplugin</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enaplugin</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the specified plugin.</para>

</sect1>


<sect1 id="func:enatimer">
<title id="func:enatimer.title"><function>$world-&gt;enatimer</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enatimer</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the timer identified by number or name. If there are
several timers with the same name, enables them all. Several arguments
can be passed at once.</para>

</sect1>


<sect1 id="func:enatrigger">
<title id="func:enatrigger.title">
  <function>$world-&gt;enatrigger</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;enatrigger</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Enables the trigger identified by number or name. If there are
several triggers with the same name, enables them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:gag">
<title id="func:gag.title"><function>$world-&gt;gag</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;gag</function></funcdef>
    <paramdef>
      <parameter>pattern</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Adds a gag that prevents lines matching pattern from being
shown.</para>

<para>See the <xref linkend="func:trigger" endterm="func:trigger.title"/> function for more advanced
options.</para>

</sect1>


<sect1 id="func:getconntime">
<title id="func:getconntime.title">
  <function>$world-&gt;getconntime</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$seconds = <function>$world-&gt;getconntime</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function returns the time spent connected to the world, in
seconds.</para>

</sect1>


<sect1 id="func:getentryfont">
<title id="func:getentryfont.title">
  <function>$world-&gt;getentryfont</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$font = <function>$world-&gt;getentryfont</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function returns the name of the font used in the command
entry box.</para>

</sect1>


<sect1 id="func:getidletime">
<title id="func:getidletime.title">
  <function>$world-&gt;getidletime</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$seconds = <function>$world-&gt;getidletime</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function returns the idle time, that is, the time elapsed
since the last command was sent, in seconds. See <xref linkend="sec:we_statusbar"/> for information on how that time is
calculated and how to configure it.</para>

</sect1>


<sect1 id="func:getkeycode">
<title id="func:getkeycode.title">
  <function>$world-&gt;getkeycode</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$keycode = <function>$world-&gt;getkeycode</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>After running this function, press a key (or a combination of
keys). The keycode (to be used in the <xref linkend="func:macro" endterm="func:macro.title"/> function) will be returned and also
printed in the screen.</para>

</sect1>


<sect1 id="func:getmainfont">
<title id="func:getmainfont.title">
  <function>$world-&gt;getmainfont</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$font = <function>$world-&gt;getmainfont</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function returns the name of the font used in the main MUD
window, that is, where the output of the world appears.</para>

</sect1>


<sect1 id="func:getname">
<title id="func:getname.title">
  <function>$world-&gt;getname</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$name = <function>$world-&gt;getname</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function returns the name of the world.</para>

</sect1>


<sect1 id="func:getpluginversion">
<title id="func:getpluginversion.title">
<function>$world-&gt;getpluginversion</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$version = <function>$world-&gt;getpluginversion</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions returns the version of the plugin with the given
name. If no plugin with that name is loaded, it returns an empty
string.</para>

</sect1>


<sect1 id="func:hook">
<title id="func:hook.title"><function>$world-&gt;hook</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;hook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>action</parameter>
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;hook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
    <paramdef>
      [<parameter>action</parameter>]
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>A hook is an action that is connected to an event, such as
connecting to the World or the window receiving focus. This functions
allow you to define a hook for a given event, that will execute
<parameter>action</parameter>, or to edit the hook identifyed by
<parameter>number</parameter>.</para>

<para>Here are the events currently supported:</para>

<itemizedlist>
  <listitem><para><literal>OnConnect</literal>: This hook is execued
  when a connection to the world is made, after the auto-logon has
  taken place (if applicable).</para></listitem>

  <listitem><para><literal>OnDisconnect</literal>: This hook is executed
  when you are disconnected from a World, after the connection has
  been closed.</para></listitem>

  <listitem><para><literal>OnReceivedText</literal>: Executed when
  text is received from the world.</para></listitem>

  <listitem><para><literal>OnSentCommand</literal>: Executed after a
  command is sent to the world. The command is available for the hook
  in the <varname>$hookdata</varname> variable, and can be inspectd in
  Perl scripts.</para></listitem>

  <listitem><para><literal>OnGetFocus</literal>: Executed when the
  KildClient window receives the focus.</para></listitem>

  <listitem><para><literal>OnLoseFocus</literal>: Executed when the
  KildClient window loses the focus.</para></listitem>

  <listitem><para><literal>OnCloseDisconnected</literal>: Executed when the
  world is forcedly closed. This can happen using the
<menuchoice>
  <guimenu>World</guimenu>
  <guimenuitem>Close</guimenuitem>
</menuchoice>
menu, the <function>$world-&gt;close()</function> function, or by
quitting the program with the world connected. You can put in this
hook, for example "<userinput>quit</userinput>" to always exit the MUD
nicely, even if you close the world by mistake.</para></listitem>
</itemizedlist>

<para><parameter>atributes</parameter> is a reference to a hash
defining attributes for the hook. Generally the call works like
this:</para>

<programlisting>
$world-&gt;hook("event", "action", { attribute1 =&gt; value1,
                                  attribute2 =&gt; value2, ... })
</programlisting>

<para>Possible attributes:</para>

<itemizedlist>
  <listitem><para><literal>action</literal>: The action to be
  executed.</para></listitem>

  <listitem><para><literal>enabled</literal>: If value evaluates to
  true, the hook is enabled. If it evaluates to false, the hook
  is disbled and is not executed.</para></listitem>

  <listitem><para><literal>name</literal>: Assigns a name to the
  hook, so that it can be referenced by name.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="func:hookenabled">
<title id="func:hookenabled.title">
  <function>$world-&gt;hookenabled</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>result = <function>$world-&gt;hookenabled</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions checks whether the specified hook exists and
whether it is enabled.</para>

<para>The first argument is the name of the event. For the second, you
can pass either a hook number or name. If the hook does not exist,
this function returns <literal>undef</literal>, so you can distinguish
the case of a non-existant hook from a disabled one.</para>

<para>If the hook exists, then the function returns 0 or 1 depending
on whether it is enabled or not. If you pass a name, and there are
several hooks with the same name, it returns a list with one value for
each hook with that name, and each value is 0 or 1 depending on the
state of the hook.</para>

</sect1>


<sect1 id="func:listalias">
<title id="func:listalias.title">
  <function>$world-&gt;listalias</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listalias</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Briefly lists all defined aliases.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listalias</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Lists detailedly the alias with the given number or name. If
there are several aliases with the same name, lists them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:listhook">
<title id="func:listhook.title">
  <function>$world-&gt;listhook</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listhook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This function briefly lists all hooks connected to the given
event.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listhook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Lists detailedly the hook with the given number or name,
connected to the specified event. If there are several hooks with the
same name, lists them all. Several arguments can be passed at
once.</para>

</sect1>


<sect1 id="func:listmacro">
<title id="func:listmacro.title">
  <function>$world-&gt;listmacro</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listmacro</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Briefly lists all defined macros.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listmacro</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Lists detailedly the macro with the given number or name. If
there are several macros with the same name, lists them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:listpermanent">
<title id="func:listpermanent.title">
  <function>$world-&gt;listpermanent</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listpermanent</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>This function prints a list of all variables that are defined as
permanent, that is, variables that will be saved when you close the
world and have their values restores when the world is
re-opened.</para>

</sect1>


<sect1 id="func:listplugin">
<title id="func:listplugin.title">
  <function>$world-&gt;listplugin</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listplugin</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Briefly lists all loaded plugins.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listplugin</function></funcdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Gives detailed information on the given plugin.</para>

</sect1>


<sect1 id="func:listtimer">
<title id="func:listtimer.title">
  <function>$world-&gt;listtimer</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listtimer</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Briefly lists all defined timers.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listtimer</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Lists detailedly the timer with the given number or name. If
there are several timers with the same name, lists them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:listtrigger">
<title id="func:listtrigger.title">
  <function>$world-&gt;listtrigger</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listtrigger</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Briefly lists all defined triggers.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;listtrigger</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Lists detailedly the trigger with the given number or name. If
there are several triggers with the same name, lists them all. Several
arguments can be passed at once.</para>

</sect1>


<sect1 id="func:loadplugin">
<title id="func:loadplugin.title">
  <function>$world-&gt;loadplugin</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$success = <function>$world-&gt;loadplugin</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
  <funcprototype>
    <funcdef>$success = <function>$world-&gt;loadplugin</function></funcdef>
    <paramdef>
      <parameter>file</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Loads a plugin. You can either pass a full path for the file
that defines the plugin, or just its name. If you provide only the
name, a file with that name (and the extesion <filename class="extension">.pl</filename>, if the extension is not already
provided) will be looked for in the directories specified by the
<varname>@PLUGINDIRS</varname> array. By default, this array contain
two directories: one where KildClient stores some of its files
(generally <filename class="directory">/usr/local/share/kildclient/plugins</filename>) and
one in the user's home directory (<filename class="directory">~/.kildclient/plugins</filename>), but feel free to
add more directories to search plugins for.</para>

<para>This function returns true if the plugin was successfully
loaded, and false otherwise (including the case in which the plugin
was already loaded). See also <xref linkend="func:requireplugin" endterm="func:requireplugin.title"/> for a way to load a plugin
unless it is already loaded.</para>

</sect1>


<sect1 id="func:logfile">
<title id="func:logfile.title">
  <function>$world-&gt;logfile</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;logfile</function></funcdef>
    <paramdef>
      <parameter>file</parameter>
    </paramdef>
    <paramdef>
      [<parameter>timeformat</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Starts logging to the given file. Everything output by the mud
will be saved. If <parameter>timeformat</parameter> is specified, it
is considered a string to be passed to the C
<function>strftime()</function> function, with special tags that are
replace with the current time and/or date, and the resulting string is
prefixed to each line. (See the strftime manual page for the possible
tags.) If this argument is not given, nothing is prefixed to the
lines.</para>

<para>It is not possible to log to more than one file at one time, if
there is already a log file open, it will be closed and logging will
continue to the new file.</para>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;logfile</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>With no arguments, this function stops logging output.</para>

</sect1>


<sect1 id="func:macro">
<title id="func:macro.title"><function>$world-&gt;macro</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;macro</function></funcdef>
    <paramdef>
      <parameter>keycode</parameter>
    </paramdef>
    <paramdef>
      <parameter>action</parameter>
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;macro</function></funcdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
    <paramdef>
      [<parameter>keycode</parameter>
    </paramdef>
    <paramdef>
      [<parameter>action</parameter>]]
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Creates a new macro, or edits the macro identified by number.
<parameter>keycode</parameter> represents a key such as
"<literal>KP_Home</literal>" or "<literal>&lt;Control&gt;F12</literal>".
The format is the one accepted by the GTK+ function
<function>gtk_accelerator_parse()</function>, but most of the time you
will want to use the <xref linkend="func:getkeycode" endterm="func:getkeycode.title"/> function to retrieve the keycode
for a given key. <parameter>action</parameter> is what will be
executed when the key (or keys) is pressed.</para>

<para>Atributes is a reference to a hash defining attributes for
the macro. Generally the call works like this:</para>

<programlisting>
$world-&gt;macro("keycode", "action", { attribute1 =&gt; value1,
                                     attribute2 =&gt; value2, ... })
</programlisting>

<para>Possible attributes:</para>

<itemizedlist>
  <listitem><para><literal>key</literal>: The key code.</para></listitem>

  <listitem><para><literal>action</literal>: The action to be
  executed.</para></listitem>

  <listitem><para><literal>enabled</literal>: If value evaluates to
  true, the macro is enabled, if false, it is disabled and is not run
  if the key is pressed.</para></listitem>

  <listitem><para><literal>name</literal>: Assigns a name to the
  macro, so that it can be referenced by name.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="func:macroenabled">
<title id="func:macroenabled.title">
  <function>$world-&gt;macroenabled</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>result = <function>$world-&gt;macroenabled</function></funcdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions checks whether the specified macro exists and
whether it is enabled.</para>

<para>You can pass either a macro number or name. If the macro does
not exist, this function returns <literal>undef</literal>, so you can
distinguish the case of a non-existant macro from a disabled
one.</para>

<para>If the macro exists, then the function returns 0 or 1 depending
on whether it is enabled or not. If you pass a name, and there are
several macros with the same name, it returns a list with one value
for each macro with that name, and each value is 0 or 1 depending on
the state of the macro.</para>

</sect1>


<sect1 id="func:movetimer">
<title id="func:movetimer.title">
  <function>$world-&gt;movetimer</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;movetimer</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>new_pos</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Moves the timer with the given name or number so that it
occupies the position <parameter>new_pos</parameter> after execution
of this function. Other timers might be moved up or down in result of
this. If <parameter>new_pos</parameter> is negative or greater than
the number of timers, the timer is moved to the last position.</para>

<para>If there are several timers with the given name, only the first
one found is moved.</para>

</sect1>


<sect1 id="func:makepermanent">
<title id="func:makepermanent.title">
  <function>$world-&gt;makepermanent</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;makepermanent</function></funcdef>
    <paramdef>
      <parameter>var</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This function marks one or more variables as permanent, that is,
the values of these variables will be saved when the world is closed,
and reloaded when the World is opened, thus keeping their values
between successive uses of the World.</para>

<para>The names of the variables are passed as a string, including the
<literal>$</literal>, <literal>@</literal> or <literal>%</literal>
prefix. Be careful to use single quotes (or <literal>\</literal>
inside double quotes) to avoid variable interpolation.</para>

</sect1>


<sect1 id="func:maketemporary">
<title id="func:maketemporary.title">
  <function>$world-&gt;maketemporary</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;maketemporary</function></funcdef>
    <paramdef>
      <parameter>var</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This function marks one or more variables as temporary, that is,
the values of these variables will not be saved when the World is
closed. This is the standard behaviour for variables, so this function
is only needed to undo the efects of the <xref linkend="func:makepermanent" endterm="func:makepermanent.title"/>
function.</para>

<para>The names of the variables are passed as a string, including the
<literal>$</literal>, <literal>@</literal> or <literal>%</literal>
prefix. Be careful to use single quotes (or <literal>\</literal>
inside double quotes) to avoid variable interpolation.</para>

</sect1>


<sect1 id="func:movealias">
<title id="func:movealias.title">
  <function>$world-&gt;movealias</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;movealias</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>new_pos</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Moves the alias with the given name or number so that it
occupies the position <parameter>new_pos</parameter> after execution
of this function. Other aliases might be moved up or down in result of
this. If <parameter>new_pos</parameter> is negative or greater than
the number of aliases, the alias is moved to the last position.</para>

<para>If there are several aliases with the given name, only the first
one found is moved.</para>

</sect1>


<sect1 id="func:movehook">
<title id="func:movehook.title">
  <function>$world-&gt;movehook</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;movehook</function></funcdef>
    <paramdef>
      <parameter>event</parameter>
    </paramdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>new_pos</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Moves the hook with the given name or number, connected to the
given event, so that it occupies the position
<parameter>new_pos</parameter> after execution of this function. Other
hooks might be moved up or down in result of this. If
<parameter>new_pos</parameter> is negative or greater than the number
of hooks, the hook is moved to the last position.</para>

<para>If there are several hooks with the given name, only the
first one found is moved.</para>

</sect1>


<sect1 id="func:movemacro">
<title id="func:movemacro.title">
  <function>$world-&gt;movemacro</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;movemacro</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>new_pos</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Moves the macro with the given name or number so that it
occupies the position <parameter>new_pos</parameter> after execution
of this function. Other macros might be moved up or down in result of
this. If <parameter>new_pos</parameter> is negative or greater than
the number of macros, the macro is moved to the last position.</para>

<para>If there are several macros with the given name, only the first
one found is moved.</para>

</sect1>


<sect1 id="func:movetrigger">
<title id="func:movetrigger.title">
  <function>$world-&gt;movetrigger</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;movetrigger</function></funcdef>
    <paramdef>
      <parameter>number/name</parameter>
    </paramdef>
    <paramdef>
      <parameter>new_pos</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Moves the trigger with the given name or number so that it
occupies the position <parameter>new_pos</parameter> after execution
of this function. Other triggers might be moved up or down in result
of this. If <parameter>new_pos</parameter> is negative or greater than
the number of triggers, the trigger is moved to the last
position.</para>

<para>If there are several triggers with the given name, only the
first one found is moved.</para>

</sect1>


<sect1 id="func:next">
<title id="func:next.title">
  <function>$world-&gt;next</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;next</function></funcdef>
    <paramdef>
      [<parameter>number</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>If used without arguments, this function focuses the next open
World. You can also give a numeric argument X, in this case it focuses
the Xth World after the current one.</para>

</sect1>


<sect1 id="func:prev">
<title id="func:prev.title">
  <function>$world-&gt;prev</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;prev</function></funcdef>
    <paramdef>
      [<parameter>number</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>If used without arguments, this function focuses the previous
open world. You can also give a numeric argument X, in this case it
focuses the Xth world before the current one.</para>

</sect1>


<sect1 id="func:reconnect">
<title id="func:reconnect.title">
  <function>$world-&gt;reconnect</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;reconnect</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>When in offline mode, this function will attempt to reconnect to
the mud.</para>

</sect1>


<sect1 id="func:requireplugin">
<title id="func:requireplugin.title">
  <function>$world-&gt;requireplugin</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$success = <function>$world-&gt;requireplugin</function></funcdef>
    <paramdef>
      <parameter>name</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This function is similar to <xref linkend="func:loadplugin" endterm="func:loadplugin.title"/>, but first checks if the plugin is
already loaded. If it is, it returns successfully. If not, it tries
loading the plugin (silently). If this succeeds, the function returns
successfully, if not, it <function>die</function>()'s. This function
is useful in plugins that require other plugins, and is meant to be
called in a <literal>BEGIN</literal> block of a plugin that requires
another.</para>

<para>The argument passed must be the name of the plugin (a path to
the file is not allowed, unlike with <xref linkend="func:loadplugin" endterm="func:loadplugin.title"/>. See <xref linkend="func:loadplugin" endterm="func:loadplugin.title"/> for
information on how plugins are found.</para>

</sect1>


<sect1 id="func:save">
<title id="func:save.title">
  <function>$world-&gt;save</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;save</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Saves the current World.</para>

</sect1>


<sect1 id="func:send">
<title id="func:send.title"><function>$world-&gt;send</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;send</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sends any number of strings to the current world. After each
string, a newline is send, so that the MUD recognizes it as a
command.</para>

<para>See also <xref linkend="func:echo" endterm="func:echo.title"/>,
<xref linkend="func:sendecho" endterm="func:sendecho.title"/> and
<xref linkend="func:sendnoecho" endterm="func:sendnoecho.title"/>.</para>

</sect1>


<sect1 id="func:sendecho">
<title id="func:sendecho.title"><function>$world-&gt;sendecho</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;sendecho</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sends any number of strings to the current world. After each
string, a newline is send, so that the MUD recognizes it as a
command.</para>

<para>The commands are always echoed to the window, regardless of the
setting of the command echo option (see <xref linkend="sec:we_misc"/>).</para>

<para>See also <xref linkend="func:send" endterm="func:send.title"/>
and <xref linkend="func:sendnoecho" endterm="func:sendnoecho.title"/>
.</para>

</sect1>


<sect1 id="func:sendfile">
<title id="func:sendfile.title"><function>$world-&gt;sendfile</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;send</function></funcdef>
    <paramdef>
      <parameter>file</parameter>
    </paramdef>
    <paramdef>
      [<parameter>delay</parameter>
    </paramdef>
    <paramdef>
      [<parameter>n-lines</parameter>]]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sends the contents of the given file to the world.
<parameter>delay</parameter> is the number of seconds to wait between
sending each group of lines, and <parameter>n-lines</parameter> is the
number of lines to send a time. If these values are not specified,
they are taken from the defauls set in the Preferences dialog.</para>

<para>If the file does not exist or cannot be open, this function
simply does nothing.</para>

</sect1>


<sect1 id="func:sendnoecho">
<title id="func:sendnoecho.title"><function>$world-&gt;sendnoecho</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;sendnoecho</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sends any number of strings to the current world. After each
string, a newline is send, so that the MUD recognizes it as a
command.</para>

<para>The commands are not echoed to the window, regardless of the
setting of the command echo option (see <xref linkend="sec:we_misc"/>).</para>

<para>See also <xref linkend="func:send" endterm="func:send.title"/>
and <xref linkend="func:sendecho" endterm="func:sendecho.title"/>
.</para>

</sect1>


<sect1 id="func:setstatus">
<title id="func:setstatus.title">
  <function>$world-&gt;setstatus</function>
</title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;setstatus</function></funcdef>
    <paramdef>
      <parameter>text</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sets the text in the main window status bar to the given
text.</para>

</sect1>


<sect1 id="func:timer">
<title id="func:timer.title"><function>$world-&gt;timer</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;timer</function></funcdef>
    <paramdef>
      <parameter>attributes</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;timer</function></funcdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
    <paramdef>
      <parameter>attributes</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Creates a new timer, or edits the timer identified by
number.</para>

<para><parameter>atributes</parameter> is a reference to a hash
defining attributes for the timer. Generally the call works like
this:</para>

<programlisting>
$world-&gt;timer({ attribute1 =&gt; value1,
                attribute2 =&gt; value2, ... })
</programlisting>

<para>Possible attributes:</para>

<itemizedlist>
  <listitem><para><literal>interval</literal>: Number of seconds
  between each execution. Required.</para></listitem>

  <listitem><para><literal>count</literal>: Number of times to execute
  the timer. After this number of executions, the timer will be
  automatically disabled or deleted (see <literal>temporary</literal>
  flag below). If <literal>count</literal> is not given or
  <literal>count</literal> is -1, the timer repeats until manually
  disabled or deleted.</para></listitem>

  <listitem><para><literal>action</literal>: The action to execute.
  Required.</para></listitem>

  <listitem><para><literal>temporary</literal>: If set to 1, the timer
  will be deleted (and not only disabled) after
  <literal>count</literal> executions have happened.</para></listitem>

  <listitem><para><literal>enabled</literal>: If set to 1, the timer
  is enabled and will execute every <literal>count</literal> seconds.
  If set to 0, the timer does not execute until enabled again. New
  timers are created enabled by default.</para></listitem>

  <listitem><para><literal>name</literal>: Assigns a name to the
  timer, so that it can be referenced by name.</para></listitem>
</itemizedlist>

</sect1>


<sect1 id="func:timerenabled">
<title id="func:timerenabled.title">
  <function>$world-&gt;timerenabled</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>result = <function>$world-&gt;timerenabled</function></funcdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions checks whether the specified timer exists and
whether it is enabled.</para>

<para>You can pass either a timer number or name. If the timer does
not exist, this function returns <literal>undef</literal>, so you can
distinguish the case of a non-existant timer from a disabled
one.</para>

<para>If the timer exists, then the function returns 0 or 1 depending
on whether it is enabled or not. If you pass a name, and there are
several timers with the same name, it returns a list with one value
for each timer with that name, and each value is 0 or 1 depending on
the state of the timer.</para>

</sect1>


<sect1 id="func:trigger">
<title id="func:trigger.title"><function>$world-&gt;trigger</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;trigger</function></funcdef>
    <paramdef>
      <parameter>pattern</parameter>
    </paramdef>
    <paramdef>
      <parameter>action</parameter>
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;trigger</function></funcdef>
    <paramdef>
      <parameter>number</parameter>
    </paramdef>
    <paramdef>
      [<parameter>pattern</parameter>
    </paramdef>
    <paramdef>
      [<parameter>action</parameter>]]
    </paramdef>
    <paramdef>
      [<parameter>attributes</parameter>]
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Creates a new trigger, or edits the trigger identified by
<parameter>number</parameter>, matching <parameter>pattern</parameter>
(a Perl regular expression), that will execute
<parameter>action</parameter> when a line is matched by
<parameter>pattern</parameter>. <parameter>action</parameter> is
interpreted as if it were typed in the command box. Simple strings get
sent to the world, Perl code can be run by prefixing it with
'<literal>/</literal>', etc.</para>

<para><parameter>atributes</parameter> is a reference to a hash
defining attributes for the trigger. Generally the call works like
this:</para>

<programlisting>
$world-&gt;trigger("pattern", "action", { attribute1 =&gt; value1,
                                       attribute2 =&gt; value2, ... })
</programlisting>

<para>Possible attributes:</para>

<itemizedlist>
  <listitem><para><literal>pattern</literal>: The pattern to
  match.</para></listitem>

  <listitem><para><literal>action</literal>: The action to be
  executed.</para></listitem>

  <listitem><para><literal>enabled</literal>: If value evaluates to
  true, the trigger is enabled. If it evaluates to false, the trigger
  is disbled and lines are not matched against it.</para></listitem>

  <listitem><para><literal>name</literal>: Assigns a name to the
  trigger, so that it can be referenced by name.</para></listitem>

  <listitem><para><literal>ignorecase</literal>: If value evaluates to
  true, ignore case when matching the pattern.</para></listitem>

  <listitem><para><literal>gag</literal>: If value evaluates to true,
  the line that triggered it is not printed.</para></listitem>

  <listitem><para><literal>gaglog</literal>: If value evaluates to
  true, the line that triggered it is not written to the log
  file.</para></listitem>

  <listitem><para><literal>keepexecuting</literal>: If the value
  evaluates to true, when a line matches the trigger, the actions for
  the trigger are executed, and matching of the line continues against
  other triggers. If this is false (the default), when this trigger
  matches no other triggers are matched.</para></listitem>

  <listitem><para><literal>rewriter</literal>:This trigger is a
  rewriter trigger. It is run before other triggers, does not prevent
  any other trigger from running (even if keepexecuting is false), and
  can alter the input line for further processing by changing the
  <varname>$colorline</varname> variable. For more details, see <xref
  linkend="sec:trigger_rewriter"/>.</para></listitem>

  <listitem><para><literal>style</literal>: Used to control the
  changing of styles (color, attributes, etc.) of a matched part of
  the line. The value of this attribute is an anonymous hash that
  specifies everything that is to be changed.</para>

  <para>Here's an example:</para>

<example id="ex:highlight_trigger"><title>Changing styles with triggers</title>
<programlisting>
$world->trigger('Joe', { name => 'joe', style => { enabled => 1,
                                                   fg => 16 } });
</programlisting>
</example>

  <para>These are the valid attributes:</para>

  <itemizedlist>
  <listitem><para><literal>enabled</literal>: Set this to 1 to enable
  changing the style.</para></listitem>

  <listitem><para><literal>target</literal>: What to highlight.
  Possible values are:</para>

  <screen>
  -1 - The whole matched line
   0 - The whole substring that matched
   1 - The first captured substring
   2 - The second captured substring
   3 - etc.
  </screen></listitem>

  <listitem><para><literal>fg</literal>: What to do with the
  foreground colour. -1 means not to change it. Other values change to
  the given color, as follows:</para>

  <screen>
  0 - black                  9 - black (bold)
  1 - red                   10 - red (bold)
  2 - green                 11 - green (bold)
  3 - yellow                12 - yellow (bold)
  4 - blue                  13 - blue (bold)
  5 - magenta               14 - magenta (bold)
  6 - cyan                  15 - cyan (bold)
  7 - white                 16 - white (bold)
  8 - the default color     17 - default bold color
  </screen></listitem>

  <listitem><para><literal>bg</literal>: What to do with the
  background color. The values are the same as for the foreground
  color.</para></listitem>

  <listitem><para><literal>italics</literal>: Italics setting. -1
  means do not change. 0 means to not use italics, and 1 means to use
  it.</para></listitem>

  <listitem><para><literal>strike</literal>: Strike-thru setting. -1
  means do not change. 0 means disable it, and 1 means enable
  it.</para></listitem>

  <listitem><para><literal>underline</literal>: Underline setting. -1
  means no change. 0 means no underline. 1 means single underline, and
  2 means double underline.</para></listitem>
  </itemizedlist>
  </listitem>

</itemizedlist>

</sect1>


<sect1 id="func:triggerenabled">
<title id="func:triggerenabled.title">
  <function>$world-&gt;triggerenabled</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>result = <function>$world-&gt;triggerenabled</function></funcdef>
    <paramdef>
      <parameter>name/number</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>This functions checks whether the specified trigger exists and
whether it is enabled.</para>

<para>You can pass either a trigger number or name. If the trigger
does not exist, this function returns <literal>undef</literal>, so you
can distinguish the case of a non-existant trigger from a disabled
one.</para>

<para>If the trigger exists, then the function returns 0 or 1
depending on whether it is enabled or not. If you pass a name, and
there are several triggers with the same name, it returns a list with
one value for each trigger with that name, and each value is 0 or 1
depending on the state of the trigger.</para>

</sect1>


<sect1 id="func:writetolog">
<title id="func:writetolog.title"><function>$world-&gt;writetolog</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>$world-&gt;writetolog</function></funcdef>
    <paramdef>
      <parameter>str</parameter>
    </paramdef>
    <paramdef>
      <parameter>...</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Writes the given line to the log file, if any. If logging is not
currently enabled, then this function does nothing.</para>

<para>Each argument is a complete line, that is written preceded by a
timestamp, if this is enabled, to the log file. If the string has ANSI
codes or codes used by the <xref linkend="func:colorize" endterm="func:colorize.title"/> function, they will be stripped and
not written to the log file.</para>

<para>See also <xref linkend="func:logfile" endterm="func:logfile.title"/>.</para>

</sect1>

</appendix>



<appendix id="app:KCWin"><title>Using KCWin for Input/Output
Windows</title>

<para><literal>KCWin</literal> is a standard plugin distributed with
KildClient that allows you to create windows with a terminal for
output and an entry box for input. These windows do nothing by
themselves, but they can be used by other plugins when they need a
window for input and output. The output area supports ANSI colors and
thus is like a mini MUD window.</para>

<para>This plugin requires the gtk2-perl bindings. It will fail to run
if these bindings are not found.</para>

<para>This plugin is more often used as a helper for other plugins. A
plugin that uses <literal>KCWin</literal> should use
<literal>$::world-&gt;requireplugin('KCWin')</literal> in a
<literal>BEGIN</literal> block, as described in <xref linkend="sec:pluginsrequiringothers"/>.</para>

<para>Use <function>KCWin-&gt;new</function> to create a new window.
<classname>KCWin</classname> derives from
<classname>Gtk2::Window</classname> so you can use all of its
methods.</para>

<para>The widgets are accessible for customization. If
<varname>$kcw</varname> is a <classname>KCWin</classname>, the
following widgets are available:</para>

<itemizedlist>
  <listitem><para><varname>$kcw-&gt;{VBOX}</varname>,
  <classname>Gtk2::VBox</classname>, the vertical box that contains
  the output and input areas.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{SCROLLWIN}</varname>,
  <classname>Gtk2::ScrolledWindow</classname>Gtk2::ScrolledWindow, this
  holds the TextView that is used for output.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{TEXTVIEW}</varname>,
  <classname>Gtk2::TextView</classname>, is the widget used for
  output.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{TEXTBUFFER}</varname>,
  <classname>Gtk2::TextBuffer</classname>, for convenience, the
  TextBuffer displayed in the window.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{CMDAREA}</varname>,
  <classname>Gtk2::HBox</classname>, a box that holds a button to
  clear the input area, and the input area itself.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{BTNCLEAR}</varname>,
  <classname>Gtk2::Button</classname>, a button that clears the input
  entry widget when clicked.</para></listitem>

  <listitem><para><varname>$kcw-&gt;{ENTRY}</varname>,
  <classname>Gtk2::Entry</classname>, the input entry widget. Connect
  to the activate signal of this widget to do something when the user
  presses ENTER in this widget.</para></listitem>
</itemizedlist>

<para>The widgets can be used, and the window can be customized (by adding
other widgets, for example). Some common actions have functions in
<classname>KCWin</classname> as a shortcut. These functions will be
described in the following sections.</para>


<sect1><title>Changes from Previous Versions</title>

<para>KCWin version 1.x used a
<classname>Gnome2::Vte::Terminal</classname> for output (the same
widget that was used in the main KildClient window). KCWin version 2.x
(which comes with KildClient 2.x) has changed that in favour of a
<classname>Gtk2::TextView</classname> (to match a change in the main
KildClient program).</para>

<para>If you never used the <varname>KCWin-&gt;{VTE}</varname> variable
directly, you will not need to change anything in your plugins that
use KCWin. If you did, you will probably have to change some things.
The new <classname>Gtk2::TextView</classname> widget is accessible via
<varname>KCWin-&gt;{TEXTVIEW}</varname>, as described above.</para>

<para>Another feature that has been added is a Clear button just like
in the MUD windows, which clears the entry widget. However, most
plugins should not need to do anything to adapt themselves to
that.</para>

<para>Finally, because of the changes, some more widgets are present
in the window, and accessible via elements of the hash that holds a
<classname>KCWin</classname>. These widgets are responsible for the
layout of the window.</para>

</sect1>


<sect1 id="func:KCwin::get_text">
<title id="func:KCwin::get_text.title"><function>KCWin::get_text</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>$text = <function>KCWin::get_text</function></funcdef>
    <void/>
  </funcprototype>
</funcsynopsis>

<para>Returns the text in the entry box.</para>

</sect1>


<sect1 id="func:KCwin::set_text">
<title id="func:KCwin::set_text.title">
<function>KCWin::set_text</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>KCWin::set_text</function></funcdef>
    <paramdef>
      <parameter>$text</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Sets the text in the entry box.</para>

</sect1>


<sect1 id="func:KCwin::feed">
<title id="func:KCwin::feed.title"><function>KCWin::feed</function></title>

<funcsynopsis>
  <funcprototype>
    <funcdef>void <function>KCWin::feed</function></funcdef>
    <paramdef>
      <parameter>$text</parameter>
    </paramdef>
  </funcprototype>
</funcsynopsis>

<para>Appends text to the output terminal widget. $text can contain
ANSI color sequences. The <xref linkend="func:colorize" endterm="func:colorize.title"/> function can be useful in conjuntion
with this function.</para>

</sect1>


</appendix>



<appendix><title>Writing Plugins</title>

<para>This appendix will describe how you can write your own plugins
for KildClient. It will describe the format of the plugin file, what
it should have, and some guidelines that all plugins should
follow.</para>

<para>The first thing to decide when writing a plugin is the name.
Since each plugin defines a Perl package, the name should be a valid
name for a Perl package. Moreover, it is a good practice to name the
plugin file with the name of the plugin (although the name of the file
could be different), so stick with letters, numbers, and the
underscore. It should not start with an underscore, however, because
all identifiers that start with an underscore are understood to be
interal of KildClient.</para>


<sect1><title>The File Format</title>

<para>The plugin file is just a Perl file that is read and run by
KildClient when the plugin is loaded. This file can call KildClient's
functions to add triggers, aliases, macros or timers, to set permanent
variables, etc. It usually also defines new subroutines for use in the
triggers, etc, or to be called directly by the user.</para>

<para>However, the plugin file must with a header, which has a fixed
format. If the header is not in this format, the plugin will not be
recognized. The header is shown in <xref linkend="fig:plugin_header"/>.</para>

<figure id="fig:plugin_header"><title>The Plugin Header</title>
<programlisting>
package NAME;
#: Version: VERSION
#: Description: ONE LINE DESCRIPTION
#: Author: AUTHOR'S NAME (OPTIONAL)
</programlisting>
</figure>

<para>The first line defines the plugin's name, which will be used to
refer to it later. It also starts a Perl package. All plugins define a
package, so that one plugin's functions do not interfere with other
plugin's ones.</para>

<para>The second line specifies the plugin's version. This is most
informative, but is also used by KildClient to ensure that only one
version of the plugin is loaded.</para>

<para>Next, there comes a short one-line description of the plugin.
It should be brief but descriptive, and it is shown in the output of
the <function>$world-&gt;listplugin</function> function.</para>

<para>Finally, it is possible to inform the author of the plugin. This
line, however, is not required, but the author's name will appear in
the plugin listing if it is informed.</para>

<para>After that, comes the plugin code. This is just Perl code,
executed by KildClient when the plugin is loaded (with
<function>do</function>).</para>

</sect1>


<sect1><title>A Sample Plugin</title>

<para>Here is a simple but complete plugin. It will be used to
illustrate many things about plugins.</para>

<example><title>A Sample Plugin</title>
<programlisting>
package sample;
#: Version: 1.0
#: Description: A Sample Plugin
#: Author: Eduardo M Kalinowski

$::world-&gt;trigger('First', 'of the plugin', { name =&gt; 'sample:misc' });
$::world-&gt;trigger('Second', 'of the plugin', { name =&gt; 'sample:misc' });

$::world-&gt;timer({ interval =&gt; 5, action =&gt; 'sample plugin',
                  name =&gt; 'sample:misc' });

$::world-&gt;macro('F8', '/sample::stop',  { name =&gt; 'sample:enadis' });
$::world-&gt;macro('F9', '/sample::start', { name =&gt; 'sample:enadis' });


sub testplugin {
  $::world-&gt;echonl("The plugin works.");
}

sub stop {
  $::world-&gt;distimer('sample:misc');
}

sub start {
  $::world-&gt;enatimer('sample:misc');
}

sub help {
  $::world-&gt;echonl("This is a sample plugin, that does nothing useful.");
  $::world-&gt;echonl("It outputs a short string every now and them. This");
  $::world-&gt;echonl("behaviour can be stopped by pressing the F8 key, and");
  $::world-&gt;echonl("re-enabled with the F9 key.");
  $::world-&gt;echonl("One function is defined: sample::testplugin. It");
  $::world-&gt;echonl("outputs something to show that the plugin is working.");
}
</programlisting>
</example>

<para>The first thing in the file is the header, in the format
described above. then comes trigger, timer, and macro definitions. All
definitions of triggers, aliases, macros, timers, hook and permanent
variables, if any, should be in the top-level scope (which means they
will be executed when the plugin is loaded). (Alternatively, you could
put them in a <literal>BEGIN</literal> block, which would have the
same result, but there isn't a reason for that.) You should not create
any of those objects in any function.</para>

<para>It should be noted that the <varname>$world</varname> variable
is refereed as <varname>$::world</varname>. It is just because we are
inside a package, and <varname>$world</varname> does not belong to
this package. Otherwise, the calls are equal.</para>

<para>After that, some functions are defined.
<function>testplugin</function> is meant to be called by the user.
<function>stop</function> and <function>start</function> are used by
the macros (but they could also be called by the user). Finally, a
<function>help</function> is defined, that outputs some information
about the plugin. All plugins should define a
<function>help</function> describing themselves.</para>

</sect1>


<sect1><title>Disposing Data When the Plugin Is Unloaded</title>

<para>If the plugin defines a function called
<literal>UNLOAD</literal>, this function will be called when the
plugin is unloaded. Currently this happens only when the World that
loaded the plugin is closed.</para>

<para>If your plugin must dispose of anything it created that would be
kept behind even when the World is closed, the
<literal>UNLOAD</literal> function is the place to do that.</para>

</sect1>


<sect1><title>Enabling and Disabling Plugins</title>

<para>As described in <xref linkend="chap:plugins"/>, the user can
enable or disable plugins. By default, disabling a plugin means
disabling all its triggers, macros, aliases, hooks and timers, and
enabling a plugin means enabling all the above items.</para>

<para>Most of the times that is enough, but for some plugins this
naive approach may not be appropriate. One such case is when a plugin
has some triggers (or any other kind of item) that is not necessarily
always enabled, and whose status is set by some other means.</para>

<para>In these cases, you can define two functions named
<literal>ENABLE</literal> and <literal>DISABLE</literal>. These will
be called when the plugin is being enabled and disabled, respectively,
and you can do whatever is necessary in there.</para>

<para>If these functions are defined, then the standard behaviour
(enabling or disabling all items) is <emphasis>not</emphasis> done,
and you must do whatever is necessary by yourself. Also, no message is
printed, so you might want to print some informative message.</para>

<para>The functions should return a true value to indicate success. If
for some reason the operation could not be done and the status should
not be changed, return a false value and the status of the plugin will
not be altered. But use this feature with care.</para>

<para>If the functions are not defined, then the default behavior
described above is used. So if your plugin doesn't have special needs,
you do not need to define these functions.</para>

</sect1>


<sect1><title>Conditional Loading of Plugins</title>

<para>If your plugin depends on some condition to be successfully
loaded, you should include a test for whatever is required in a
<literal>BEGIN</literal> block, and if the conditions are not present,
you should call the Perl <function>die</function> function passing a
descriptive message telling why the plugin could not be loaded.</para>

<para>For example, here is part of a hypothetical spell-checker plugin
that uses the file <filename>/usr/share/dict/words</filename>
file:</para>

<example><title>Conditional loading of plugins</title>
<programlisting>
package spellcheck;
#: Version: 1.0
#: Description: Spell Checker
#: Author: Somebody

BEGIN {
  die("Word file (/usr/share/dict/words) could not be read")
    unless -r /usr/share/dict/words;
}

...
</programlisting>
</example>

<para>When the user tries to load that plugin, the test will be made.
If the file cannot be read (because it does not exist, or the
permissiosn are wrong, or for any other reason),
<function>die</function> will be called, the plugin will not be
loaded, and the given message will be printed in the screen.</para>


<sect2 id="sec:pluginsrequiringothers">
<title>Plugins That Require Other Plugins</title>

<para>If your plugin requires some other plugin, you should use the
<function>$world-&gt;requireplugin</function> function in a
<literal>BEGIN</literal> block. This function will verify if the named
plugin is already loaded. If it is, it returns successfully. If it is
not loaded, the function will try to load the plugin. If it could be
loaded, the function exits successfully. If, however, the plugin
could not be loaded (because it was not found, or because it failed
some condition), <function>$world-&gt;requireplugin</function> will call
<function>die</function>, which will abort the loading the plugin that
required the other plugin.</para>

<para>As an example, consider the plugin foo, which requires the bar
plugin:</para>

<example><title>A plugin that requires another</title>
<programlisting>
package foo;
#: Version: 1.0
#: Description: The Super Frobnicator
#: Author: Somebody

BEGIN {
  $::world-&gt;requireplugin('bar');
}

...
</programlisting>
</example>

<para>If foo was loaded successfully, you can be sure that the bar
plugin and its functionality is present. If bar could not be loaded,
foo will not be loaded.</para>

</sect2>

</sect1>


<sect1><title>Using GTK+ From Plugins</title>

<para>With the use of the gtk2-perl bindings, it is possible to use
the full power of the GTK+ library in KildClient plugins. This allows
you to create dialogs, windows, message boxes, and anything else your
plugin needs.</para>

<para>Using gtk2-perl in a KildClient plugin is straightforward, there
is just a couple of points to be observed. Import the Perl modules as
usual, generally with a line like this: "<literal>use Gtk2
-init;</literal>". Create windows and display them as usual. The
biggest difference is that you must not call
<literal>Gtk2-&gt;main</literal>. Since KildClient is a GTK+ application,
it already runs a main loop, and starting another one would lock
KildClient and make it unresponsive. Also, you must never call
<literal>Gtk2-&gt;main_quit</literal>, because that would cause
KildClient to quit. Even tough the world would be saved, the user
certainly wouldn't want that.</para>

<para>All features of GTK+ are supported, as are all of gtk2-modules
(this includes modules for the base libraries Glid and GDK, and also
for other libraries such as the Gnome ones). Notably, Gtk2::GladeXML
is supported, which allows you to create complex user interfaces
visually and load them from the .glade file in the plugin.</para>

<para>Note that having the gtk2-perl bindings is not necessary to run
KildClient. If they are not present, however, it will not be possible
to run plugins that use it, naturally. The plugins will not be loaded
because an error will be generated when the modules are loaded (in the
"<literal>use Gtk2 -init;</literal>" line).</para>

<para>The example below shows a very simple (and not very useful)
plugin using gtk2-perl. It should show how simple it is to use the
gtk2-perl bindings in KildClient plugin.</para>

<example><title>A plugin that uses gtk2-perl</title>
<programlisting>
package gtksample;
#: Version: 1.0.0
#: Description: A Plugin Using gtk2-perl
#: Author: Eduardo M Kalinowski

use Gtk2 -init;

# Is the window being displayed?
our $window_displayed = 0;

# Widgets
our $window;
our $entry;
our $button;

sub help {
  $::world-&gt;echonl("This plugins demonstrates the use of gtk2-perl under KildClient.",
                   "It does nothing really useful.",
                   "",
                   "Enter /gtksample::run to try it.");
}


sub run {
  return if $window_displayed;

  $window = Gtk2::Window-&gt;new();
  $window-&gt;set_title("gtk2-perl test");
  $window-&gt;signal_connect(delete_event =&gt; sub {
                            $window_displayed = 0;
                            return 0;
                          });

  my $vbox = Gtk2::VBox-&gt;new(0, 8);

  $entry = Gtk2::Entry-&gt;new();
  $entry-&gt;set_text("Type something here");
  $vbox-&gt;pack_start($entry, 0, 1, 0);

  $button = Gtk2::Button-&gt;new("And click me");
  $button-&gt;signal_connect(clicked =&gt; \&amp;on_button_clicked);
  $vbox-&gt;pack_start($button, 0, 1, 0);

  $window-&gt;add($vbox);

  $window-&gt;show_all();
  $window_displayed = 1;
}


sub on_button_clicked {
  $button-&gt;set_label($entry-&gt;get_text());
}


sub UNLOAD {
  $window-&gt;destroy if $window_displayed;
}
</programlisting>
</example>

<para>Notice how it defines a <literal>UNLOAD</literal> function that
destroys the window if it is being displayed. Plugins that open
windows almost always need such a function to delete the windows that
are still open when the World is closed. If these windows are not
closed, the program will most likely crash if the user tries to use
them after the Worlds has been closed, so make sure they get
deleted.</para>

<para>For more information on gtk2-perl, see <ulink url="http://http://gtk2-perl.sourceforge.net/">http://gtk2-perl.sourceforge.net/</ulink>.</para>

</sect1>


<sect1><title>Plugin Conventions</title>

<para>The first convention about plugins has been mentioned already:
all plugins should define a <function>help</function> describing
themselves. This help can be as detailed as necessary.</para>

<para>Another convention regards the use of triggers, aliases, macros,
timers and hooks. All of them should have names (and they should
always be referenced by names, because the plugin writer cannot know
which number will be assigned to them), and the names should consist
of the name of the plugin, a colon, and then some descriptive name for
the trigger (or alias, etc). This is to avoid name clashes with other
plugins.</para>

<para>Another aspect regarding triggers, aliases, macros, timers and
hooks is that they should only be created in the top-level scope,
which means they are created when the plugin is loaded. They must not
be created in a function that is called later, because this way they
would not be recognized as belonging to the plugin, and this would
create a mess for the user. So create them outside any
functions.</para>

</sect1>

</appendix>

</part>

</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:nil
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->