irssi/docs/PERL

 Functions that you can use in Irssi's Perl scripts
 --------------------------------------------------

This is just my very first implementation and things will probably change.

Commands marked with (!!) mean that you shouldn't use it unless you
know what you're doing..

If there's a "Xxxx::" text before the command, it means that it belongs to
that package. Like "Server::command" means that you should either call it as
  Irssi::Server::command($server, $cmd);
or more easily:
  $server->command($cmd);

Commands that don't have the Xxxx prefix are called as Irssi::command();

A list of signals that irssi send can be found from SIGNALS file.


 *** General

Channel cur_channel() - return current channel
Server cur_server() - return current server

channels() - return list of all channels
servers() - return list of all servers
commands() - return list of all commands
dccs() - return list of all dcc connections
logs() - return list of all log files
plugins() - return list of all plugins

print(str)
  Print `str' to current window as "Irssi notice".

command(cmd, [Server server, [Channel channel]])
  Send a command `cmd' (in current channel). This will work just as if you
  had typed `cmd' in command line, so you'll need to use /COMMANDS or the
  text will be sent to the channel.

Server::command(cmd, [Channel channel])
  Just like above, except different calling method.

Channel::command(cmd)
  Just like above, except different calling method.

Server::printtext(channel, level, str)
  Print `str'.


 *** Message levels

level2bits(level)
  Level string -> number

bits2level(bits)
  Level number -> string

combine_level(level, str)
  Combine level number to level string ("+level -level").
  Return new level number.


 *** Signals / timeouts

signal_emit(signal, ...)
  Send signal `signal'

signal_add(signal, func)
  Bind `signal' to function `func'

signal_remove(signal, func)
  Unbind `signal' from function `func'

tag timeout_add(msecs, func, data)
  Call `func' every `msecs' milliseconds (1000 = 1 second) with
  parameter `data'. Returns tag which can be used to stop the timeout.

timeout_remove(tag)
  Remove timeout with tag.


 *** Commands

Command::values()
  Get some information about command. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"cmd" - Command
	"category" - Category

command_bind(cmd, category, func)
  Bind command `cmd' to call function `func'. `category' is the
  category where the command is displayed in /HELP.

command_unbind(cmd, func)
  Unbind command `cmd' from function 'func.

Server::command_split(cmd, arg, max_nicks)
  Split the `cmd' into several commands so `arg' argument has only
  `max_nicks' number of nicks.

  Example: $server->command_split("KICK nick1,nick2,nick3 :byebye", 1, 2);
  Irssi will send commands "KICK nick1,nick2 :byebye" and
  "KICK nick3 :byebye" to server.


 *** Server functions

Server::values()
  Get some information about server. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"address" - Address where we connected (irc.blah.org)
	"real_address" - Who the server thinks it is (irc1.blah.org)
	"port" - Port where we connected
	"tag" - Unique server tag.
	"ircnet" - IRC network
	"password" - Password we used in connection.

	"nick" - Current nick
	"wanted_nick" - Nick which we would prefer to use
	"username" - User name
	"realname" - Real name
	"usermode" - Current user mode
	"connected" - Is connection finished? 1|0
	"connection_lost" - Did we lose the connection (1) or was
	                    the connection meant to be disconnected (0)
  Example:
	%server_info = %{Irssi::cur_server->values()};
	Irssi::print("Current server = ".$server_info{'address'});

Server server_connect(address, [port=6667, [password='', [nick='']]])
  Create new server connection.

Server::disconnect()
  Disconnect from server.

Server server_find_tag(tag)
  Find server with tag

Server server_find_ircnet(ircnet)
  Find first server that is in `ircnet'

Channel channel_find_any(channel)
  Find `channel' from any server

Server::send_raw(cmd)
  Send raw message to server, it will be flood protected so you
  don't need to worry about it.

Server::ctcp_send_reply(data)
  Send CTCP reply. This will be "CTCP flood protected" so if there's too
  many CTCP requests in buffer, this reply might not get sent.


 *** Server redirections

WARNING: It's easy to mess up the Irssi's internal server expectations with
these commands!

This is a powerful feature of Irssi that I can't seen in other IRC clients.
You can EASILY grab the server's reply for a command you send to server
without any horrible kludges.

Server::redirect_init(command, last, ...)
  Initialize redirection for specified command. This needs to be done only
  once. Irssi already initializes commands "WHOIS", "WHO", "LIST" and "ISON".
  `command' is the whole name of the signal, like "command whois".
  `last' specifies how many of the items in `...' is considered as the
  "last event" from the command.

  Example: $server->redirection_init('command who',
        2, # 2 first events will finish the command
	'event 401', # unknown nick (finished)
	'event 315', # end of who (finished)
	'event 352'); # who line (wait..)

Server::redirect_event(arg, last, ...)
  Add redirection. `arg' is a space separated list of arguments that should
  match before Irssi will redirect the event (think of /WHOIS nick nick and
  doing another to different nick immediately after it, there's no way of
  knowing which will return first. so, arg would be in this case 'nick').

  `last' specifies how many of the following events are considered as
  "last event" from command - just like in redirect_init().

  `...' is `event, signal, argpos, ...`, where
  `event' is the event we're waiting from server.
  `signal' is the signal we will send after receiving the event. It should
           always start with 'redir ' so that Irssi's perl handler knows to
	   send correct arguments to signal handler.
  `argpos' is the argument position in event's data or -1 if it
           should be ignored.

  Example:
	$server->send_raw('WHOIS :cras');
	$server->redirect_event('cras', 2,
			  "event 318", "redir end_of_whois", -1,
			  "event 402", "redir no_such_server", -1,
			  "event 401", "redir no_such_nick", 1,
			  "event 311", "redir whois", 1,
			  "event 301", "redir whois_away", 1,
			  "event 312", "redir whois_server", 1,
			  "event 313", "redir whois_oper", 1,
			  "event 317", "redir whois_idle", 1,
			  "event 319", "redir whois_channels", 1);
  In the 402-case we tried "/WHOIS nick nick" but nick didn't exist..

group Server::redirect_single_event(arg, last, group, event, signal, argpos)
  Same as redirect_event() except you can set it up in pieces.
  If `group' is 0, it will create new group and return it's id.


 *** IRC masks

irc_mask_match(mask, nick, user, host)
  Return 1 if `mask' matches nick!user@host.

irc_mask_match_address(mask, nick, address)
  Return 1 if `mask' matches nick!address.

irc_masks_match(masks, nick, address)
  Return 1 if any mask in the `masks' (string separated with spaces)
  matches nick!address.

irc_get_mask(nick, host, flags)
  Create IRC mask from nick!host.
  flags = you need to combine these:
  (FIXME: export the IRC_xxx defines to perl (or something))
	IRC_MASK_NICK   0x01
	IRC_MASK_USER   0x02
	IRC_MASK_HOST   0x04
	IRC_MASK_DOMAIN 0x08


 *** Channels

Channel::values()
  Get some information about channel. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"name" - channel name
	"type" - channel type ("channel", "query", "dcc chat", "empty")
	"password" - channel password

Channel Server::channel_create(channel, type, automatic)
  Create new channel with name `channel'. `type' is one of:
  (FIXME: export these to perl somehow)
    CHANNEL_TYPE_CHANNEL   0
    CHANNEL_TYPE_QUERY	   1
    CHANNEL_TYPE_DCC_CHAT  2
    CHANNEL_TYPE_EMPTY	   3
  `automatic' means that channel is created "automatically" and
  Irssi will NOT change the active window to it.

Channel::destroy()
  Destroy channel.

Channel::change_name(name)
  Change channel's name

Channel::get_mode()
  Return channel's mode

Channel Server::channel_find(channel)
  Find `channel' in server.

Channel Server::channel_find_closest(channel, level)
  Find `channel' or if not found, some other channel that has
  level `level' (number).

Channel channel_find_level(level)
  Find channel with level `level'.


 *** Channel modes

Ban::values()
  Get some information about ban. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"ban" - The ban
	"setby" - Nick of who set the ban
	"time" - Timestamp when ban was set

Ban Channel::ban_add(ban, nick, time)
  Add new ban. (!!)

Channel::ban_remove(ban)
  Remove ban. (!!)

Ban Channel::ban_exception_add(ban, nick, time)
  Add ban exception (!!)

Channel::ban_exception_remove(ban)
  Remove ban exception (!!)

Channel::invitelist_add(mask)
  Add invite (!!)

Channel::invitelist_remove(mask)
  Remove invite (!!)

Channel::modes_parse_channel(setby, modestr)
  Parse mode string (!!)

Channel::ban_get_mask(nick)
  Get ban mask for `nick'.

Channel::modes_set(data, mode)
  Set mode `mode' ("+o", "-o", etc.) to all nicks in `data'
  separated with spaces.


 *** Nick list

Nick::values()
  Get some information about nick. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"nick" - Plain nick
	"host" - Host (blah@there.org)
	"name" - Real name
	"op", "voice", "gone", "ircop" - 1 or 0
	"last_check" - timestamp when last checked gone/ircop status.
	"send_massjoin" - Waiting to be sent in a "massjoin" signal - 1 or 0

Nick Channel::nicklist_insert(nick, op, voice, send_massjoin)
  Add nick to nicklist. (!!)

Channel::nicklist_remove(nick)
  Remove nick from nicklist. (!!)

Nick Channel::nicklist_find(mask)
  Find nick from nicklist.

Channel::nicklist_getnicks(channel)
  Return a list of all nicks (Nick packages) in channel.


 *** DCC

Dcc:destroy()
  Destroy DCC connection. (!!)

dcc_type2str(type)
  DCC type number to string

dcc_str2type(type)
  DCC type string to number

Dcc dcc_find_item(type, nick, arg)
  Find DCC connection.

Dcc dcc_find_by_port(nick, port)
  Find DCC connection by port.


 *** Netsplits

Netsplit::values()
  Get some information about netsplit. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"nick" - Nick
	"address" - Nick's host
	"server" - The server nick was in
	"destserver" - The other server where split occured.
	"destroy" - Timestamp when this record should be destroyed
	/*FIXME: add list of channels the nick was in;*/

Netsplit Server::netsplit_find(nick, address)
  Check if nick!address is on the other side of netsplit. Netsplit records
  are automatically removed after 30 minutes (current default)..

Nick Server::netsplit_find_channel(nick, address, channel)
  Find nick record for nick!address in channel `channel'.


 *** Notify list

notifylist_add(nick, ircnet)
  Add `nick' to notify list in irc network `ircnet'

Server notifylist_ison(nick, ircnets)
  Check if `nick' is in IRC. `ircnets' is a space separated
  list of irc networks. If it's empty string, all servers will be checked.

Server::notifylist_ison_server(nick)
  Check if `nick' is on IRC server.


 *** Rawlog

Server::rawlog_input(str)
  Send `str' to raw log as input text. (!!)

Server::rawlog_output(str)
  Send `str' to raw log as output text. (!!)

Server::rawlog_redirect(str)
  Send `str' to raw log as redirection text. (!!)


 *** Ignores

Autoignore::values()
  Get some information about autoignore. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"nick" - Ignored nick
	"timeleft" - Seconds left to ignore
	"level" - Ignoring level number

ignore_add(mask, level)
  Ignore `mask' with level string

ignore_remove(mask, level)
  Unignore level string from `mask'

Server::ignore_check(nick, host, type)
  Return 1 if nick!host is ignored with level number `type'.

Server::autoignore_add(type, nick)
  Autoignore `nick' in server with level number `type'.

Server::autoignore_remove(mask, level)
  Remove autoignoring `nick' from server. `level' is a string.


 *** Logging

Log::values()
  Get some information about log. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"fname" - Log file name
	"autoopen_log" - Automatically open log at startup
	"last" - Timestamp when last write occured.
	"level" - Global logging level.
	/*FIXME: add list of Logitems;*/

Logitem::values()
  Get some information about logitem. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"name" - Log item name.
	"level" - Logging level number.

Log log_create(fname, data)
  Create log file. `data' = logging level ("-all #channel +public")

Log log_create_with_level(fname, level)
  Create log file with level number.

Log log_file_find(fname)
  Find log file.

Log::destroy()
  Destroy log file

Log::open()
  Start logging

Log::close()
  Stop logging

Log::append_item(name, level)
  Append log item with level number `level' to log file. (!!)

Log::remove_item(log, name)
  Remove log item. (!!)


 *** Plugins

Plugin::values()
  Get some information about plugin. This function returns a reference to
  hash table (FIXME: can't it return the hash table itself?!). Hash table
  has keys:
	"name" - Plugin name
	"description" - Plugin description

plugin_load(name, args)
  Load plugin.

plugin_get_description(name)
  Get plugin description string.

Plugin plugin_find(name)
  Find plugin.