1
0
mirror of https://github.com/irssi/irssi.git synced 2024-10-06 04:53:38 -04:00
irssi/docs/perl.txt
Timo Sirainen c96a0d2ac5 Implemented Irssi::print_window(), added optional level parameter to
Irssi::print()


git-svn-id: http://svn.irssi.org/repos/irssi/trunk@597 dbcabf3a-b0e7-0310-adc4-f8d773084564
2000-08-13 13:54:34 +00:00

648 lines
19 KiB
Plaintext

Running Perl scripts
--------------------
FIXME: part of this file is out of date..
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.