[index]
Use
   help 'functionname'
to get help on that function. The quotes are necessary.

[colorize]
&Dcolorize function: COLORIZEs a string

&cSyntax: $color = colorize(str)

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.

Color code table (based on colors used by the Smaug server):

  &0 (number zero) - Reset all attributes and colors to default
Normal colors:
  &x - Black                     &r - Red
  &g - Green                     &O - Yellow
  &b - Blue                      &p - Magenta
  &c - Cyan                      &w - White
  &d - Default foreground
Bold colors:
  &z - Bold Black                &R - Bold Red
  &G - Bold Green                &Y - Bold Yellow
  &B - Bold Blue                 &P - Bold Magenta
  &C - Bold Cyan                 &W - Bold White
  &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)
  &_ - Underline on              ^_ - All underline off
  &= - Double underline on
  &| - Strikethrough on          ^| - Strikethrough off
  &/ - Italics on                ^/ - Italics off
  &i - Inverse video on          ^i - Inverse video off
  &h - Hidden mode on            ^h - Hidden mode off

Note: 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.

Note: to insert a & or ^ character, use && and ^^, respectively.

You can also also use colorize() to display text in any color of a 6x6x6
RGB color cube. To do so, use &rgbX and ^rgbX to set the foreground and
background, respectively. r, g, and b 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.

Finally, to select one of the 24 shades of gray available, use &nG and ^nG
for the foreground and background, respectively, where n is an integer from
0 to 23, and G is really the letter G.

You can use the kc256 (see section 'kc256' in the Manual) plugin to display
all the colors for you to choose from.

[getclientname]
&Dgetclientname function: GETs the CLIENT's NAME

&cSyntax: $name = getclientname()

This function returns the name of the client, that is, "KildClient".

[getversion]
&Dgetversion function: GETs the KildClient VERSION number

&cSyntax: $version = getversion()

This function returns the version number of KildClient.

[getworld]
&Dgetworld function: GETs a pointer to a WORLD

&cSyntax: $var = getworld(name)

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).

For example:

$coolmud = getworld("CoolMud");
$coolmud->send("quit");

This will send "quit" to the CoolMud world.

[gotow]
&Dgotow function: GOes TO a World

&cSyntax: gotow(number)
&c        gotow(name)

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.

[help]
&Dhelp function: displays HELP

&cSyntax: help('function')

Displays help for the given function. The name of the function is passed as
a string, so it must be in quotes.

[play]
&Dplay function: PLAYs a sound file

&cSyntax: play(file)

This function plays a sound file. The argument is the path to the file.

[quit]
&Dquit function: QUITs the program

&cSyntax: quit()

Disconnects and closes all Worlds and KildClient exits.

[stripansi]
&Dstripansi function: STRIPs ANSI sequences from the string

&cSyntax: $stripped = stripansi(str)

Returns the string stripped of any ANSI sequences that it had.

[stripcolorize]
&Dstripcolorize function: STRIPs COLORIZE sequences from the string

&cSyntax: $stripped = stripcolorize(str)

Returns the string stripped of any sequences used by colorize() to add
color to it.

[$window->getsize] [getsize]
&D$window->getsize function: GETs the current window SIZE

&cSyntax: ($lines, $columns) = $window->getsize()
&c        $columns = $window->getsize()

This function 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.

[$window->minimize] [minimize]
&D$window->minimize function: MINIMIZEs the window

&cSyntax: $window->minimize()

This function minimized KildClient's main window. Called from a macro, it
makes a nice boss key. :-)

[$window->settitle] [settitle]
&D$window->settitle function: SETs the window TITLE

&cSyntax: $window->settitle(newtitle)

Sets the title of the window to the given string.

[$window->seturgencyhint] [seturgencyhint]
&D$window->seturgencyhint function: SETs the URGENCY window HINT

&cSyntax: $window->seturgencyhint(boolean)

Sets the value of the window's "urgency" flag to true or false. This is a
request for attention to the window, and usually will make the window title
flash. However, note that the actual behavior depends on the window manager
used.

[$world->alias] [alias]
&D$world->alias function: creates an ALIAS

&cSyntax: $world->alias(pattern, substitution, [attributes])
&c        $world->alias(number, [pattern, [substitution]], [attributes])

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
s/pattern/substitution/ structure.)

Be careful that any part of the command can match. To match only the exact
string, use something like '^command$'. To match only in the beginning of
the line, use '^command'.

Atributes is a reference to a hash defining attributes for the alias.
Generally the call works like this:

$world->alias("pattern", "substitution", { attribute1 => value1,
                                           attribute2 => value2, ... })

Possible attributes:

  * pattern: The pattern to match.

  * substitution: The substitution to do.

  * ignorecase: If value evaluates to true, ignore case when matching the
    pattern.

  * perleval: If true, the substitution is made passing the "e" flag
    (s/pattern/substitution/e), so substitution should be actually Perl
    statements to be evaluated when there is a match.

  * enabled: If value evaluates to true, the alias is enabled, if false, it
    is disabled and commands are not matched against it.

  * name: Assigns a name to the alias, so that it can be referenced by
    name.

[$world->aliasenabled] [aliasenabled]
&D$world->aliasenabled function: checks whether a ALIAS is ENABLED

&cSyntax: $result = $world->aliasenabled(name)
&c        $result = $world->aliasenabled(number)

This function checks whether the specified alias exists and whether it is
enabled.

You can pass either a alias number or name. If the alias does not exist,
this function returns undef, so you can distinguish the case of a
non-existant alias from a disabled one.

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.

[$world->close] [close]
&D$world->close function: CLOSEs the current world

&cSyntax: $world->close()

Disconnects and closes the current world, immediately.

[$world->cmdseparator] [cmdseparator]
&D$world->cmdseparator function: sets or gets the CoMmanD SEPARATOR

&cSyntax: $world->cmdseparator(string)

When called with an argument, this sets the command separator for the
current world to the given value. For more details of the command
separator, see section 'Interacting with the MUD' in the Manual and section
'Input' in the Manual.

&cSyntax: $separator = $world->cmdseparator()

When called without arguments, it returns its current value of the command
separator.

[$world->commandecho] [commandecho]
&D$world->commandecho function: sets or gets the status of the COMMAND ECHO feature

&cSyntax: $world->commandecho(boolean)

When called 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 section 'Input' in the Manual.

&cSyntax: $status = $world->commandecho()

When called without arguments, it returns its current value of the command
echo option.

[$world->connectother] [connectother]
&D$world->connectother function: CONNECTS to anOTHER world

&cSyntax: $world->connectother()

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.

[$world->dc] [dc]
&D$world->dc function: DisConnects from world

&cSyntax: $world->dc()

Disconnects from the current world.

[$world->delalias] [delalias]
&D$world->delalias function: DELETEs an ALIAS

&cSyntax: $n = $world->delalias(name)
&c        $n = $world->delalias(number)

Deletes the alias identified by the given number or name. If there are
several aliases with the same name, deletes them all. Returns the number of
aliases deleted.

[$world->delhook] [delhook]
&D$world->delhook function: DELetes a HOOK

&cSyntax: $n = $world->delhook(event, name)
&c        $n = $world->delhook(event, number)

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. Returns the number of hooks deleted.

[$world->delmacro] [delmacro]
&D$world->delmacro function: DELETEs a MACRO

&cSyntax: $n = $world->delmacro(name)
&c        $n = $world->delmacro(number)

Deletes the macro identified by the given number or name. If there are
several macros with the same name, deletes them all. Returns the number of
macros deleted.

[$world->deltimer] [deltimer]
&D$world->deltimer function: DELETEs a TIMER

&cSyntax: $n = $world->deltimer(name)
&c        $n = $world->deltimer(number)

Deletes the timer identified by the given number or name. If there are
several timers with the same name, deletes them all. Returns the number of
timers deleted.

[$world->deltrigger] [deltrigger]
&D$world->deltrigger function: DELETEs a TRIGGER

&cSyntax: $n = $world->deltrigger(name)
&c        $n = $world->deltrigger(number)

Deletes the trigger identified by the given number or name. If there are
several triggers with the same name, deletes them all. Returns the number
of triggers deleted.

[$world->disalias] [disalias]
&D$world->disalias function: DISables an ALIAS

&cSyntax: $world->disalias(name/number, ...)

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.

[$world->dishook] [dishook]
&D$world->dishook function: DISables a HOOK

&cSyntax: $world->dishook(event, name/number, ...)

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.

[$world->dismacro] [dismacro]
&D$world->dismacro function: DISables a MACRO

&cSyntax: $world->dismacro(name/number, ...)

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.

[$world->displugin] [displugin]
&D$world->displugin: DISables a PLUGIN

&cSyntax: $world->displugin(name)

Disables the specified plugin.

[$world->distimer] [distimer]
&D$world->distimer function: DISables a TIMER

&cSyntax: $world->distimer(name/number, ...)

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.

[$world->distrigger] [distrigger]
&D$world->distrigger function: DISables a TRIGGER

&cSyntax: $world->distrigger(name/number, ...)

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.

[$world->echo] [echo]
&D$world->echo function: ECHOes something to the terminal window

&cSyntax: $world->echo(str, ...)

Prints the strings in the terminal window. They are not sent to the world.

See also world_echonl(), world_send().

[$world->echonl] [echonl]
&D$world->echonl function: ECHOes to the terminal window, followed by NewLine

&cSyntax: $world->echonl(str, ...)

Prints the strings in the terminal window, each followed by a newline. They
are not sent to the world.

See also world_echo(), world_send().

[$world->echonlandlog] [echonlandlog]
&D$world->echonlandlog function: calls ECHONL and writetoLOG

&cSyntax: $world->echonlandlog(str, ...)

This is a convenience function that just calls world_echonl() and
world_writetolog() for each argument, thus writing the given line(s) to the
screen and to the log file.

[$world->enaalias] [enaalias]
&D$world->enaalias function: ENAbles an ALIAS

&cSyntax: $world->enaalias(name/number, ...)

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.

[$world->enahook] [enahook]
&D$world->enahook function: ENAbles a HOOK

&cSyntax: $world->enahook(event, name/number, ...)

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.

[$world->enamacro] [enamacro]
&D$world->enamacro function: ENAbles a MACRO

&cSyntax: $world->enamacro(name/number, ...)

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.

[$world->enaplugin] [enaplugin]
&D$world->enaplugin: ENAbles a PLUGIN

&cSyntax: $world->enaplugin(name)

Enables the specified plugin.

[$world->enatimer] [enatimer]
&D$world->enatimer function: ENAbles a TIMER

&cSyntax: $world->enatimer(name/number, ...)

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.

[$world->enatrigger] [enatrigger]
&D$world->enatrigger function: ENAbles a TRIGGER

&cSyntax: $world->enatrigger(name/number, ...)

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.

[$world->expandalias] [expandalias]
&D$world->expandalias function: EXPANDs ALIASes in a string

&cSyntax: $result = $world->expandalias(string)

This function expands aliases in the string passed as argument. The result
is what you would get if you typed "string" in the input box (except that
aliases are still expanded even if Disable Aliases is selected in the
Preferences menu).

[$world->gag] [gag]
&D$world->gag function: adds a simple GAG

&cSyntax: $world->gag(pattern)

Adds a gag that prevents lines matching pattern from being shown.

See the world_trigger() function for more advanced options.

[$world->getaliasnumber] [getaliasnumber]
&D$world->getaliasnumber function: GETs an ALIAS's NUMBER

&cSyntax: @list = $world->getaliasnumber(name)

Returns a list with the number(s) of the alias(es) matching the given name.
If no alias with that name is found, returns an empty list. If there are
several aliases with the same name, returns the numbers of all of them.

The number of an alias is necessary to edit it. However, as the user can
change the order of aliases, create new ones and delete old aliases, an
alias's number may change, so you should not store its number; you must
fetch the number just before editing it.

[$world->getcharacter] [getcharacter]
&D$world->getcharacter function: GETs the name of the connected CHARACTER

&cSyntax: $name = $world->getcharacter()

If autologin was used (see section 'General' in the Manual), this function
returns the name of the character used to log in to the mud. If autologin
is disabled, this function returns undef.

[$world->getconntime] [getconntime]
&D$world->getconntime function: GETs the CONNection TIME

&cSyntax: $seconds = $world->getconntime()

This function returns the time spent connected to the world, in seconds.

[$world->getentryfont] [getentryfont]
&D$world->getentryfont function: GETs the command ENTRY box FONT

&cSyntax: $font = $world->getentryfont()

This function returns the name of the font used in the command entry box.

[$world->gethooknumber] [gethooknumber]
&D$world->gethooknumber function: GETs a HOOK's NUMBER

&cSyntax: @list = $world->gethooknumber(event, name)

Returns a list with the number(s) of the hook(s) matching the given name.
If no hook with that name is found, returns an empty list. If there are
several hooks with the same name, returns the numbers of all of them. You
must specify the event in which to search for the hook.

The number of a hook is necessary to edit it. However, as the user can
change the order of hooks, create new ones and delete old hooks, a hook's
number may change, so you should not store its number; you must fetch the
number just before editing it.

[$world->getidletime] [getidletime]
&D$world->getidletime function: GETs the IDLE TIME

&cSyntax: $seconds = $world->getidletime()

This function returns the idle time, that is, the time elapsed since the
last command was sent, in seconds. See section 'Status Bar' in the Manual
for information on how that time is calculated and how to configure it.

[$world->getinput] [getinput]
&D$world->getinput function: GETs INPUT text

&cSyntax: $text = $world->getline()

This function returns the current text in the command entry box.

[$world->getkeycode] [getkeycode]
&D$world->getkeycode function: GETs the KEYCODE for a key combination

&cSyntax: $keycode = $world->getkeycode()

After running this function, press a key (or a combination of keys). The
keycode (to be used in the world_macro() function) will be returned and
also printed in the screen.

[$world->getline] [getline]
&D$world->getline function: GETs a LINE from the scrollback buffer

&cSyntax: $text = $world->getline(line)
&c        ($text, $time) = $world->getline(line)

This function allows you to retrieve a line from the scrollback buffer, and
optionally the time in which it was received.

line can be a positive number, representing the number of the line to
fetch, or a negative number. If negative, that means that number of lines
counting from the bottom. (That is, -1 is the last received line, -2 the
one before the last, and so on.)

If the line cannot be retrieved (because it is not stored anymore), returns
undef.

The time returned is represented as the number of seconds since the epoch,
the same kind of value the time function would return.

[$world->getlogfile] [getlogfile]
&D$world->getlogfile: GETs name of LOGging FILE

&cSyntax: $file = $world->getlogfile()

This function returns the name of the file to which the output is being
logged, or undef if logging is not started for the world.

[$world->getmacronumber] [getmacronumber]
&D$world->getmacronumber function: GETs a MACRO's NUMBER

&cSyntax: @list = $world->getmacronumber(name)

Returns a list with the number(s) of the macro(s) matching the given name.
If no macro with that name is found, returns an empty list. If there are
several macros with the same name, returns the numbers of all of them.

The number of a macro is necessary to edit it. However, as the user can
change the order of macros, create new ones and delete old macros, a
macro's number may change, so you should not store its number; you must
fetch the number just before editing it.

[$world->getmainfont] [getmainfont]
&D$world->getname function: GETs the MAIN window FONT

&cSyntax: $font = $world->getmainfont()

This function returns the name of the font used in the main MUD window,
that is, where the output of the world appears.

[$world->getname] [getname]
&D$world->getname function: GETs the NAME of the world

&cSyntax: $name = $world->getname()

This function returns the name of the world.

[$world->getpluginversion] [getpluginversion]
&D$world->getpluginversion function: GETs a PLUGIN's VERSION

&cSyntax: $version = $world->getpluginversion(name)

This function returns the version of the plugin with the given name. If no
plugin with that name is loaded, it returns an empty string.

[$world->gettimernumber] [gettimernumber]
&D$world->gettimernumber function: GETs a TIMER's NUMBER

&cSyntax: @list = $world->gettimernumber(name)

Returns a list with the number(s) of the timer(s) matching the given name.
If no timer with that name is found, returns an empty list. If there are
several timers with the same name, returns the numbers of all of them.

The number of a timer is necessary to edit it. However, as the user can
change the order of timers, create new ones and delete old timers, a
timer's number may change, so you should not store its number; you must
fetch the number just before editing it.

[$world->gettriggernumber] [gettriggernumber]
&D$world->gettriggernumber function: GETs a TRIGGER's NUMBER

&cSyntax: @list = $world->gettriggernumber(name)

Returns a list with the number(s) of the trigger(s) matching the given
name. If no trigger with that name is found, returns an empty list. If
there are several triggers with the same name, returns the numbers of all
of them.

The number of a trigger is necessary to edit it. However, as the user can
change the order of triggers, create new ones and delete old triggers, a
trigger's number may change, so you should not store its number; you must
fetch the number just before editing it.

[$world->hook] [hook]
&D$world->hook function: connects a HOOK

&cSyntax: $world->hook(event, action, [attributes])
&c        $world->hook(event, number, [action], [attributes])

A hook is an action that is connected to an event, such as connecting to
the World or the window receiving focus. This function allow you to define
a hook for a given event, that will execute action, or to edit the hook
identifyed by number.

Here are the events currently supported:

  * OnConnect: This hook is execued when a connection to the world is made,
    after the auto-logon has taken place (if applicable).

  * OnDisconnect: This hook is executed when you are disconnected from a
    World, after the connection has been closed.

  * OnReceivedText: Executed when text is received from the world.

  * OnSentCommand: Executed after a command is sent to the world. The
    command is available for the hook in the $hookdata variable, and can be
    inspectd in Perl scripts.

  * OnGetFocus: Executed when the KildClient window receives the focus.

  * OnLoseFocus: Executed when the KildClient window loses the focus.

  * OnCloseConnected: Executed when the world is forcedly closed. This can
    happen using the World->Close menu, the $world->close() function, or by
    quitting the program with the world connected. You can put in this
    hook, for example "quit" to always exit the MUD nicely, even if you
    close the world by mistake.

atributes is a reference to a hash defining attributes for the hook.
Generally the call works like this:

$world->hook("event", "action", { attribute1 => value1,
                                  attribute2 => value2, ... })

Possible attributes:

  * action: The action to be executed.

  * enabled: If value evaluates to true, the hook is enabled. If it
    evaluates to false, the hook is disbled and is not executed.

  * name: Assigns a name to the hook, so that it can be referenced by name.

[$world->hookenabled] [hookenabled]
&D$world->hookenabled function: checks whether a HOOK is ENABLED

&cSyntax: $result = $world->hookenabled(event, name)
&c        $result = $world->hookenabled(event, number)

This function checks whether the specified hook exists and whether it is
enabled.

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 undef, so you can distinguish the case of a non-existant hook from
a disabled one.

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.

[$world->interpret] [interpret]
&D$world->interpret function: INTERPRETs a string as if typed in the input box

&cSyntax: $world->interpret(string)

This function interprets the string as if it were typed in the input box:
commands are split, Perl code is run, aliases are expanded, etc.

[$world->ispermanent] [ispermanent]
&D$world->ispermanent function: checks wheter a variable IS PERMANENT

&cSyntax: $return = $world->ispermanent(var)

This function tests if a variable is permanent. The return value is true or
false depending on the variable's status.

The names of the variables are passed as a string, including the $, @ or %
prefix. Be careful to use single quotes (or \ inside double quotes) to
avoid variable interpolation.

[$world->listalias] [listalias]
&D$world->listalias function: LISTs one or all ALIASes

&cSyntax: $world->listalias()

Briefly lists all defined aliases.

&cSyntax: $world->listalias(name/number, ...)

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.

[$world->listhook] [listhook]
&D$world->listhook function: LISTs connected HOOKs

&cSyntax: $world->listhook(event)

This function briefly lists all hooks connected to the given event.

&cSyntax: $world->listhook(event, name/number, ...)

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.

[$world->listmacro] [listmacro]
&D$world->listmacro function: LISTs one or all MACROs

&cSyntax: $world->listmacro()

Briefly lists all defined macros.

&cSyntax: $world->listmacro(name/number, ...)

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.

[$world->listpermanent] [listpermanent]
&D$world->listpermanent function: LISTs PERMANENT variables

&cSyntax: $world->listpermanent()

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.

[$world->listplugin] [listplugin]
&D$world->listplugin function: LISTs loaded PLUGINs

&cSyntax: $world->listplugin()

Briefly lists all loaded plugins.

&cSyntax: $world->listplugin(name)
&c        $world->listplugin(number)

Gives detailed information on the given plugin.

[$world->listtimer] [listtimer]
&D$world->listimer function: LISTs one or all TIMERs

&cSyntax: $world->listtimer()

Briefly lists all defined timers.

&cSyntax: $world->listtimer(name/number, ...)

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.

[$world->listtrigger] [listtrigger]
&D$world->listtrigger function: LISTs one or all TRIGGERs

&cSyntax: $world->listtrigger()

Briefly lists all defined triggers.

&cSyntax: $world->listtrigger(name/number, ...)

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.

[$world->loadplugin] [loadplugin]
&D$world->loadplugin function: LOADs a PLUGIN

&cSyntax: $success = $world->loadplugin(name)
&c        $success = $world->loadplugin(file)

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 .pl, if the extension is not already provided)
will be looked for in the directories specified by the @PLUGINDIRS array.
By default, this array contain two directories: one where KildClient stores
some of its files (generally /usr/local/share/kildclient/plugins) and one
in the user's home directory (~/.kildclient/plugins), but feel free to add
more directories to search plugins for.

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 world_requireplugin() for a way to load a plugin unless it is already
loaded.

[$world->logfile] [logfile]
&Dlogfile function: enables or disables LOGging the output to a FILE

&cSyntax: $world->logfile(file, [timeformat])

Starts logging to the given file. Everything output by the mud will be
saved. If timeformat is specified, it is considered a string to be passed
to the C strftime() 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.

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.

&cSyntax: $world->logfile()

With no arguments, this function stops logging output.

[$world->macro] [macro]
&D$world->macro function: creates a MACRO

&cSyntax: $world->macro(keycode, action, [attributes])
&c        $world->macro(number, [keycode, [action]], [attributes])

Creates a new macro, or edits the macro identified by number. keycode
represents a key such as "KP_Home" or "<Control>F12". The format is the one
accepted by the GTK+ function gtk_accelerator_parse(), but most of the time
you will want to use the world_getkeycode() function to retrieve the
keycode for a given key. action is what will be executed when the key (or
keys) is pressed.

Atributes is a reference to a hash defining attributes for the macro.
Generally the call works like this:

$world->macro("keycode", "action", { attribute1 => value1,
                                     attribute2 => value2, ... })

Possible attributes:

  * key: The key code.

  * action: The action to be executed.

  * enabled: If value evaluates to true, the macro is enabled, if false, it
    is disabled and is not run if the key is pressed.

  * name: Assigns a name to the macro, so that it can be referenced by
    name.

[$world->macroenabled] [macroenabled]
&D$world->macroenabled function: checks whether a MACRO is ENABLED

&cSyntax: $result = $world->macroenabled(name)
&c        $result = $world->macroenabled(number)

This function checks whether the specified macro exists and whether it is
enabled.

You can pass either a macro number or name. If the macro does not exist,
this function returns undef, so you can distinguish the case of a
non-existant macro from a disabled one.

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.

[$world->makepermanent] [makepermanent]
&D$world->makepermanent function: MAKEs variables PERMANENT

&cSyntax: $world->makepermanent(var, ...)

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.

The names of the variables are passed as a string, including the $, @ or %
prefix. Be careful to use single quotes (or \ inside double quotes) to
avoid variable interpolation.

[$world->maketemporary] [maketemporary]
&D$world->maketemporary function: MAKEs variables TEMPORARY

&cSyntax: $world->maketemporary(var, ...)

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 world_makepermanent() function.

The names of the variables are passed as a string, including the $, @ or %
prefix. Be careful to use single quotes (or \ inside double quotes) to
avoid variable interpolation.

[$world->mlsend] [mlsend]
&D$world->mlsend function: Multi-Line SEND

&cSyntax: $success = $world->mlsend(attributes)

This function emulates the Multi-line Send feature (see section 'Multi-line
Send' in the Manual) from perl scripts. Several lines can be sent at once,
optionally prefixing and/or suffixing each line with text you specify. It's
also possible to send the contents of a file to the MUD. The lines can be
sent with customized intervals between them (so as not to cause buffer
overflows that lead to a disconnection from the server).

atributes is a reference to a hash defining attributes for the timer.
Generally the call works like this:

$world->mlsend({ attribute1 => value1,
                 attribute2 => value2, ... })

Possible attributes:

  * initialtext: Lines of text to be sent to the MUD before anything else.
    You can specify this argument in two ways: one is as a string composed
    of several lines, KildClient will split the string and send each line
    separately. The second option is to pass a reference to an array, where
    each element is a line.

    The following two call are thus equivalent:

      $world->mlsend({ initialtext => "First line\nSecond line\nLast line" })
      
      $world->mlsend({ initialtext => [ "First line",
                                        "Second line",
                                        "Last line" ]})
      
  * file: The path to a file whose contents are to be sent, line by line,
    after sending the initialtext (if present), but before sending
    finaltext.

  * finaltext: Lines to be sent after the file contents has been sent (if a
    file was specified). This is very similar to initialtext, and can be
    given also as a multi-line string or as a reference to an array of
    lines.

  * linestart: If present, specifies a string that is prepended to each
    line as it is sent to the MUD.

  * lineend: If present, specifies a string that is appended to each line
    as it is sent to the MUD.

  * delay: The delay, in seconds, between each group of lines. If you are
    getting disconnected for sending too much text at once, increase this
    value. If not given, the value is taken from the Global Preferences
    (see section 'Sending' in the Manual).

  * linesatime: The number of lines to be sent at a time. If not given, the
    value is taken from the Global Preferences (see section 'Sending' in
    the Manual).

On success, returns true. If the file does not exist or cannot be open,
this function does nothing and returns a false value. It returns undef if
invalid parameters are specified.

You might also want to see the world_sendlines() and world_sendfile()
functions which are simpler ways of sending several lines or the contents
of a file at once, respectively.

[$world->movealias] [movealias]
&D$world->movealias function: MOVEs an ALIAS to another position

&cSyntax: $world->movealias(name, new_pos)
&c        $world->movealias(number, new_pos)

Moves the alias with the given name or number so that it occupies the
position new_pos after execution of this function. Other aliases might be
moved up or down in result of this. If new_pos is negative or greater than
the number of aliases, the alias is moved to the last position.

If there are several aliases with the given name, only the first one found
is moved.

[$world->movehook] [movehook]
&D$world->movehook function: MOVEs a HOOK to another position

&cSyntax: $world->movehook(event, name, new_pos)
&c        $world->movehook(event, number, new_pos)

Moves the hook with the given name or number, connected to the given event,
so that it occupies the position new_pos after execution of this function.
Other hooks might be moved up or down in result of this. If new_pos is
negative or greater than the number of hooks, the hook is moved to the last
position.

If there are several hooks with the given name, only the first one found is
moved.

[$world->movemacro] [movemacro]
&D$world->movemacro function: MOVEs a MACRO to another position

&cSyntax: $world->movemacro(name, new_pos)
&c        $world->movemacro(number, new_pos)

Moves the macro with the given name or number so that it occupies the
position new_pos after execution of this function. Other macros might be
moved up or down in result of this. If new_pos is negative or greater than
the number of macros, the macro is moved to the last position.

If there are several macros with the given name, only the first one found
is moved.

[$world->movetimer] [movetimer]
&D$world->movetimer function: MOVEs a TIMER to another position

&cSyntax: $world->movetimer(name, new_pos)
&c        $world->movetimer(number, new_pos)

Moves the timer with the given name or number so that it occupies the
position new_pos after execution of this function. Other timers might be
moved up or down in result of this. If new_pos is negative or greater than
the number of timers, the timer is moved to the last position.

If there are several timers with the given name, only the first one found
is moved.

[$world->movetrigger] [movetrigger]
&D$world->movetrigger function: MOVEs a TRIGGER to another position

&cSyntax: $world->movetrigger(name, new_pos)
&c        $world->movetrigger(number, new_pos)

Moves the trigger with the given name or number so that it occupies the
position new_pos after execution of this function. Other triggers might be
moved up or down in result of this. If new_pos is negative or greater than
the number of triggers, the trigger is moved to the last position.

If there are several triggers with the given name, only the first one found
is moved.

[$world->next] [next]
&D$world->next function: goes to the NEXT world

&cSyntax: $world->next()

When called without arguments, this function focuses the next open World.

&cSyntax: $world->next(number)

When called with a numeric argument X, it focuses the Xth World after the
current one.

[$world->path] [path]
&D$world->path function: generate sequences of directions forming a PATH

&cSyntax: $world->path(str)

str is a string defining a path. The following example shows the features
of paths:

  3n2e4n2e{ne}e{open door}3n

The general syntax syntax is "<number of repetitions><command>". "<number
of repetitions>" can be omitted, in this case it is considered as 1.
command is the command that will be repeated. If it is not a one-letter
command, it should be enclosed in braces ({}).

The example above would generate these commands:

  n
  n
  n
  e
  e
  n
  n
  n
  n
  e
  e
  ne
  e
  open door
  n
  n
  n

The commands are sent using the settings in the Sending tab of the
Preferences dialog (see section 'Sending' in the Manual).

[$world->prev] [prev]
&D$world->prev function: goes to the PREVious world

&cSyntax: $world->prev()

When called without arguments, this function focuses the previous open
world.

&cSyntax: $world->prev(number)

When called with a numeric argument X, it focuses the Xth world before the
current one.

[$world->reconnect] [reconnect]
&D$world->reconnect function: RECONNECTs to the world

&cSyntax: $world->reconnect()

When in offline mode, this function will attempt to reconnect to the mud.

[$world->requireplugin] [requireplugin]
&D$world->requireplugin function: REQUIREs a PLUGIN to be loaded

&cSyntax: $success = $world->requireplugin(name)

This function is similar to world_loadplugin(), 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 die()'s. This function is useful in plugins that
require other plugins, and is meant to be called in a BEGIN block of a
plugin that requires another.

The argument passed must be the name of the plugin (a path to the file is
not allowed, unlike with world_loadplugin(). See world_loadplugin() for
information on how plugins are found.

[$world->save] [save]
&D$world->save function: SAVEs the current world

&cSyntax: $world->save()

Saves the current World.

[$world->send] [send]
&D$world->send function: SENDs something to the world

&cSyntax: $world->send(str, ...)

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.

See also world_echo(), world_sendecho() and world_sendnoecho().

[$world->sendecho] [sendecho]
&D$world->sendecho function: SENDs something to the world, with ECHO

&cSyntax: $world->sendecho(str, ...)

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.

The commands are always echoed to the window, regardless of the setting of
the command echo option (see section 'Input' in the Manual).

See also world_send() and world_sendnoecho().

[$world->sendfile] [sendfile]
&D$world->sendfile function: SENDs a FILE to the world

&cSyntax: $success = $world->sendfile(file, [delay, [n-lines]])

Sends the contents of the given file to the world. delay is the number of
seconds to wait between sending each group of lines, and n-lines 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 (see section 'Sending'
in the Manual).

On success, returns true. If the file does not exist or cannot be open,
this function does nothing and returns a false value. It returns undef if
the file name is not specified.

For more options, see the world_mlsend() function which allows adding a
text before and/or after each line, and sending lines before and/or after
sending the contents of the file.

[$world->sendlines] [sendlines]
&D$world->sendlines function: SENDs several LINES to the world

&cSyntax: $success = $world->sendlines(multi-linestring, [delay, [n-lines]])
&c        $success = $world->sendlines([line1,line2,...], [delay, [n-lines]])

Sends several lines of text to the world. delay is the number of seconds to
wait between sending each group of lines, and n-lines 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 (see section 'Sending' in
the Manual).

There are two ways to specify the lines to be sent: the first is passing a
multi-line string, which is split into lines and each line is sent
separately. The second one is passing a reference to an array where each
element consists of one line.

This function always returns true.

For more options, see the world_mlsend() function which allows adding a
text before and/or after each line, and sending lines before and/or after
sending the contents of the file.

[$world->sendmsdpcommand] [sendmsdpcommand]
&D$world->sendmsdpcommand function: SENDs an MSDP protocol COMMAND

&cSyntax: $world->sendmsdpcommand(command, argument1, ...)

Sends a specific type of data to the server using MSDP. See section 'MSDP
data' in the Manual.

[$world->sendnoecho] [sendnoecho]
&D$world->sendnoecho function: SENDs something to the world, with NO ECHO

&cSyntax: $world->sendnoecho(str, ...)

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.

The commands are not echoed to the window, regardless of the setting of the
command echo option (see section 'Input' in the Manual).

See also world_send() and world_sendecho() .

[$world->sendserverdata] [sendserverdata]
&D$world->sendserverdata function: SENDs out-of-band DATA to the SERVER

&cSyntax: $world->sendserverdata(hash_reference)

Sens out-of-band data to the server. See section 'Sending server data' in
the Manual for details.

[$world->setinput] [setinput]
&D$world->setinput function: SETs INPUT text

&cSyntax: $world->setinput(text)

Sets the text in command entry box to the given text.

[$world->setstatus] [setstatus]
&D$world->setstatus function: SETs the STATUS bar text

&cSyntax: $world->setstatus(text)

Sets the text in the main window status bar to the given text.

[$world->silentdisalias] [silentdisalias]
&D$world->silentdisalias function: SILENTly DISables an ALIAS

&cSyntax: $world->silentdisalias(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentdishook] [silentdishook]
&D$world->silentdishook function: SILENTly DISables a HOOK

&cSyntax: $world->silentdishook(event, name/number, ...)

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. Does not print a message in the
screen in case of success.

[$world->silentdismacro] [silentdismacro]
&D$world->silentdismacro function: SILENTly DISables a MACRO

&cSyntax: $world->silentdismacro(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentdistimer] [silentdistimer]
&D$world->silentdistimer function: SILENTly DISables a TIMER

&cSyntax: $world->silentdistimer(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentdistrigger] [silentdistrigger]
&D$world->silentdistrigger function: SILENTly DISables a TRIGGER

&cSyntax: $world->silentdistrigger(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentenaalias] [silentenaalias]
&D$world->silentenaalias function: SILENTly ENAbles an ALIAS

&cSyntax: $world->silentenaalias(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentenahook] [silentenahook]
&D$world->silentenahook function: SILENTly ENAbles a HOOK

&cSyntax: $world->silentenahook(event, name/number, ...)

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. Does not print a message in the
screen in case of success.

[$world->silentenamacro] [silentenamacro]
&D$world->silentenamacro function: SILENTly ENAbles a MACRO

&cSyntax: $world->silentenamacro(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentenatimer] [silentenatimer]
&D$world->silentenatimer function: SILENTly ENAbles a TIMER

&cSyntax: $world->silentenatimer(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->silentenatrigger] [silentenatrigger]
&D$world->silentenatrigger function: SILENTly ENAbles a TRIGGER

&cSyntax: $world->silentenatrigger(name/number, ...)

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. Does not print a message in the screen in case of success.

[$world->timer] [timer]
&D$world->timer function: creates a TIMER

&cSyntax: $world->timer(attributes)
&c        $world->timer(number, attributes)

Creates a new timer, or edits the timer identified by number.

atributes is a reference to a hash defining attributes for the timer.
Generally the call works like this:

$world->timer({ attribute1 => value1,
                attribute2 => value2, ... })

Possible attributes:

  * interval: Number of seconds between each execution. Fractions of
    seconds (such as 1.5) are allowed. Required.

  * count: Number of times to execute the timer. After this number of
    executions, the timer will be automatically disabled or deleted (see
    temporary flag below). If count is not given or count is -1, the timer
    repeats until manually disabled or deleted.

  * action: The action to execute. Required.

  * temporary: If set to 1, the timer will be deleted (and not only
    disabled) after count executions have happened.

  * enabled: If set to 1, the timer is enabled and will execute every count
    seconds. If set to 0, the timer does not execute until enabled again.
    New timers are created enabled by default.

  * name: Assigns a name to the timer, so that it can be referenced by
    name.

[$world->timerenabled] [timerenabled]
&D$world->timerenabled function: checks whether a TIMER is ENABLED

&cSyntax: $result = $world->timerenabled(name)
&c        $result = $world->timerenabled(number)

This function checks whether the specified timer exists and whether it is
enabled.

You can pass either a timer number or name. If the timer does not exist,
this function returns undef, so you can distinguish the case of a
non-existant timer from a disabled one.

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.

[$world->trigger] [trigger]
&D$world->trigger function: creates a TRIGGER

&cSyntax: $world->trigger(pattern, action, [attributes])
&c        $world->trigger(number, [pattern, [action]], [attributes])

Creates a new trigger, or edits the trigger identified by number, matching
pattern (a Perl regular expression), that will execute action when a line
is matched by pattern. action 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 '/', etc.

atributes is a reference to a hash defining attributes for the trigger.
Generally the call works like this:

$world->trigger("pattern", "action", { attribute1 => value1,
                                       attribute2 => value2, ... })

Possible attributes:

  * pattern: The pattern to match.

  * action: The action to be executed.

  * enabled: 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.

  * name: Assigns a name to the trigger, so that it can be referenced by
    name.

  * ignorecase: If value evaluates to true, ignore case when matching the
    pattern.

  * gag: If value evaluates to true, the line that triggered it is not
    printed.

  * gaglog: If value evaluates to true, the line that triggered it is not
    written to the log file.

  * keepexecuting: 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.

  * rewriter: 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 $colorline variable. For more details, see
    section 'Rewriter Triggers' in the Manual.

  * style: 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.

    Here's an example:

    $world->trigger('Joe', { name => 'joe', style => { enabled => 1,
                                                       fg => 16 } });

    These are the valid attributes:

      * enabled: Set this to 1 to enable changing the style.

      * target: What to highlight. Possible values are:

          -1 - The whole matched line
           0 - The whole substring that matched
           1 - The first captured substring
           2 - The second captured substring
           3 - etc.
          
      * fg: What to do with the foreground colour. -1 means not to change
        it. Other values change to the given color, as follows:

          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
          
      * bg: What to do with the background color. The values are the same
        as for the foreground color.

      * italics: Italics setting. -1 means do not change. 0 means to not
        use italics, and 1 means to use it.

      * strike: Strike-thru setting. -1 means do not change. 0 means
        disable it, and 1 means enable it.

      * underline: Underline setting. -1 means no change. 0 means no
        underline. 1 means single underline, and 2 means double underline.

[$world->triggerenabled] [triggerenabled]
&D$world->triggerenabled function: checks whether a TRIGGER is ENABLED

&cSyntax: $result = $world->triggerenabled(name)
&c        $result = $world->triggerenabled(number)

This function checks whether the specified trigger exists and whether it is
enabled.

You can pass either a trigger number or name. If the trigger does not
exist, this function returns undef, so you can distinguish the case of a
non-existant trigger from a disabled one.

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.

[$world->writetolog] [writetolog]
&D$world->writetolog function: WRITEs something TO the LOG file

&cSyntax: $world->writetolog(str, ...)

Writes the given line to the log file, if any. If logging is not currently
enabled, then this function does nothing.

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 colorize() function, they will be stripped and not written to
the log file.

See also world_logfile().

[KCWin::get_text] [get_text]
&DKCWin::get_text function: GETs TEXT in the entry box

&cSyntax: $text = KCWin::get_text()

Returns the text in the entry box.

[KCWin::set_text] [set_text]
&DKCWin::set_text function: SETs TEXT in the entry box

&cSyntax: KCWin::set_text($ext)

Sets the text in the entry box.

[KCWin::feed] [feed]
&DKCWin::feed function: FEEDs TEXT to the window

&cSyntax: KCWin::feed(text)

Appends text to the output terminal widget. $text can contain ANSI color
sequences. The colorize() function can be useful in conjuntion with this
function.