and the docs

git-svn-id: http://svn.irssi.org/repos/irssi/trunk@173 dbcabf3a-b0e7-0310-adc4-f8d773084564

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.