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