Running Perl scripts -------------------- 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 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'. 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 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) "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 "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::cur_server->values()}; Irssi::print("Current server = ".$server_info{'address'}); Server server_connect(address, [port=6667, [password='', [nick='', [channels='']]]]) 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 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(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. 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 "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. *** Reconnects Reconnect::values() Get some information about reconnect. This function returns a reference to hash table. Hash table has keys: "tag" - Unique numeric tag "address" - Address where we're going to connect "password" - Password we use in connection "port" - Port where we're going to connect "ircnet" - IRC network "nick" - Nick we want to use "channels" - Join to these channels once connected "next_connect" - Unix time stamp when the next connection occurs *** 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.