diff options
Diffstat (limited to 'docs/perl.txt')
| -rw-r--r-- | docs/perl.txt | 621 |
1 files changed, 621 insertions, 0 deletions
diff --git a/docs/perl.txt b/docs/perl.txt new file mode 100644 index 00000000..94b83e11 --- /dev/null +++ b/docs/perl.txt @@ -0,0 +1,621 @@ + 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 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::cur_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(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 + "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: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 + "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. |