irssi/docs/perl.txt

 Running Perl scripts
 --------------------

FIXME: part of this file is out of date..
UPDATE: 0.7.96 - this is even yet more out of date ;) See scripts in
samples/ directory, they'll help you get started :)

Place new scripts to ~/.irssi/scripts/, or /usr/lib/irssi/scripts/
directory and run then with /RUN script. Or you could also run the
script from another place by specifying the whole path to it. Scripts
in ~/.irssi/scripts/autorun/ directory are automatically run at
startup.

Using /PERLFLUSH closes and reopens the perl interpreter removing all
Perl scripts from memory. There's currently no way to unload a single Perl
script. Also, Irssi doesn't check if you run the same script twice or
different scripts use signal_add() for the same named function - it will
probably crash or do some weird things then.


 Irssi's signals
 ---------------

Irssi is pretty much based on sending and handling different signals.
Like when you receive a message from server, say,
":nick!user@there.org PRIVMSG you :blahblah". Irssi will first send a
"server incoming" signal with the raw line as it's first parameter. You
probably don't want to use this signal. Next thing Irssi does is to
interpret the header and send a "server event" signal with arguments
"PRIVMSG you...", server, "nick", "user@there.org". You probably don't
want to use this either, since next irssi will send an "event privmsg"
signal with the "you :blahblah" as it's argument. You can at any point
grab the signal, do whatever you want to do with it and optionally stop
it from going any further by returning from the function with value 1. 

For example:

--------------------------------------------------------
sub event_privmsg {
	# $data = "nick/#channel :text"
	my ($data, $server, $nick, $address) = @_;
	my ($target, $text) = $data =~ /^(\S*)\s:(.*)/;

	return 1 if ($text =~ /free.*porn/);
	return 1 if ($nick =~ /idiot/);
}

Irssi::signal_add("event privmsg", "event_privmsg")
--------------------------------------------------------

This will hide all public or private messages that match the regexp
"free.*porn" or the sender's nick contain the word "idiot".

You can also use signal_add_last() if you wish to let the Irssi's internal
functions be run before yours.

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


 Message levels
 --------------

Several functions expect message levels. Sometimes numeric and sometimes
alphabetic. Yes, it's stupid, will fix it :) For now you can use 
Irssi::level2bits() function to convert the level string to numeric. Here's
all the levels that irssi supports currently:

CRAP, MSGS, PUBLIC, NOTICES, SNOTES, CTCPS, ACTIONS, JOINS, PARTS
QUITS, KICKS, MODES, SMODES, TOPICS, WALLOPS, INVITES, NICKS, PONGS
DCC, CLIENTNOTICE, CLIENTCRAP, CLIENTERROR, HILIGHT
(and NOHILIGHT if you don't want the message to be hilighted ever..)

For example:

$server->printtext("#channel", Irssi::level2bits('clientcrap'), 'Hello, world');

Writes text to #channel window with clientcrap level.


 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();


 *** General

Window active_win() - return current window
Server active_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

print(str, [level])
  Print `str' to some window (status/current probably), default level is
  "Irssi notice".

print_window(str, [level])
  Print `str' to current window, default level is "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'.

setup_get(option)
  Get value of `option' from setup and return it.


 *** 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_add_last(signal, func)
  Bind `signal' to function `func'. Call `func' as late as possible.

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. 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::irc_send_cmd_split(cmd, arg, max_nicks)
  Split the `cmd' into several commands so `arg' argument has only
  `max_nicks' number of nicks.

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


 *** Server Connects

This is a record where we keep connection information. All Servers and
Reconnects records have pointer to one of these.

Connect::values()
  Get some information about connect. This function returns a reference to
  hash table. Hash table has keys:
	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name

Connect server_create_conn(address, [port=6667, [password='', [nick='', [channels='']]]])
  Create new server connection.

 *** Server functions

Server::values()
  Get some information about server. This function returns a reference to
  hash table. Hash table has keys:
	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name

	"tag" - Unique server tag.
	"real_address" - Who the server thinks it is (irc1.blah.org)
	"nick" - Current nick
	"usermode" - Current user mode
	"usermode_away" - Are we marked as away? 1|0
	"away_reason" - Away reason
	"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::active_server->values();
	Irssi::print("Current server = ".$server_info->{'address'});

Server Connect::connect()
  Connect to server.

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(channel)
  Find `channel' from any server

Channel Server::channel_find_level(level)
  Find channel with level `level' preferably from specified server, but
  fallbacks to any channel the matching level.

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. Hash table has keys:
	"server" - Server of the channel
	"name" - Channel name
	"type" - Channel type ("channel", "query", "dcc chat", "empty")
	"topic" - Channel topic
	"key" - Channel key (password)
	"limit" - Max. users in channel (+l mode)
	"level" - Channel's level number.
	"new_data" - 0=no new data, 1=text, 2=msg, 3=msg for you
	"synced" - Channel is synchronized
	"wholist" - Channel has received /WHO list
	"names_got" - Channel has received /NAMES list
	"chanop" - You are channel operator
	"left" - You just left the channel (for "channel destroyed" event)
	"kicked" - You was just kicked out of the channel (for
	           "channel destroyed" event)

Channel Server::channel_create(type, automatic)
  Create new channel with name `channel'. `automatic' means that channel is
  created "automatically", Irssi won't 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. 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. Hash table has keys:
	"nick" - Plain nick
	"host" - Host (blah@there.org)
	"name" - Real name
	"hops" - Hop count to the server nick is using
	"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::values()
  Get some information about nick. This function returns a reference to
  hash table. Hash table has keys:
	"type" - Type of the DCC: chat, send, get
	"created" - Unix time stamp when the DCC record was created

	"server" - Server where the DCC was initiated.
	"chat" - DCC chat record if the request came through DCC chat
	"ircnet" - IRC network where the DCC was initiated.
	"mynick" - Our nick to use in DCC chat.

	"nick" - Other side's nick name.
	"addr" - Other side's IP address.
	"port" - Port we're connecting in.

	"arg" - Given argument .. file name usually
	"file" - The real file name which we use.

	"size" - File size
	"transfd" - Bytes transferred
	"skipped" - Bytes skipped from start (resuming file)
	"starttime" - Unix time stamp when the DCC transfer was started

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

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

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

dcc_ctcp_message(target, server, chat, notice, msg)
  Send a CTCP message/notify to target. Send the CTCP via DCC chat if
  `chat' is specified.

Dcc::dcc_chat_send(data)
  Send `data' to dcc chat.

Dcc item_get_dcc(item)
  If window item `item' is a query of a =nick, return DCC chat record
  of nick.

 *** Reconnects

Reconnect::values()
  Get some information about reconnect. This function returns a reference to
  hash table. Hash table has keys:
	"tag" - Unique numeric tag
	"next_connect" - Unix time stamp when the next connection occurs

	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name


 *** Netsplits

Netsplit::values()
  Get some information about netsplit. This function returns a reference to
  hash table. 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. 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. 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. 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. 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.