mirror of
https://github.com/irssi/irssi.git
synced 2024-09-08 04:26:01 -04:00
git-svn-id: http://svn.irssi.org/repos/irssi/trunk@775 dbcabf3a-b0e7-0310-adc4-f8d773084564
650 lines
19 KiB
Plaintext
650 lines
19 KiB
Plaintext
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.
|