Perl documentation and updates

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

5 files changed, 517 insertions, 3 deletions

diff --git a/NEWS b/NEWS
index 4c711c60..949bc9fb 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,24 @@
-v0.7.25 2000-02-19  Timo Sirainen <tss@iki.fi> [stable]
+v0.7.27 2000-02-26  Timo Sirainen <tss@iki.fi>
+
+	* Perl support - finally! Took only a year or so to imlement it ;)
+	  Well, I could have done it ages ago but it wouldn't have had
+	  all the flexibility it now has - you should be able to do almost
+	  anything with perl scripts. See DOCS/PERL for some documentation
+	  and examples/ directory for couple of example scripts.
+
+	  This is the very first version and I haven't even tested that all
+	  functions work correctly! Any suggestions are welcome. I don't
+	  really like the values() functions so if someone knows better ways
+	  to them I'd really like to hear.
+
+	  BTW. I haven't had time to learn Perl well yet, so my scripts are
+	  probably not the best examples.. :)
+
+v0.7.26 2000-02-19  Timo Sirainen <tss@iki.fi>
+
+	-
+
+v0.7.25 2000-02-19  Timo Sirainen <tss@iki.fi>
 
 	+ /WQUERY - create query to current window
 	+ Irssi doesn't close the window anymore when using /PART
diff --git a/docs/Makefile.am b/docs/Makefile.am
index ac39dcc4..c2d6f6c2 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -2,6 +2,8 @@ EXTRA_DIST = \
 	FAQ \
 	COMMANDS \
 	FORMATS \
+	PERL \
+	SIGNALS \
 	botnet.txt
 
 SUBDIRS = help
diff --git a/docs/PERL b/docs/PERL
new file mode 100644
index 00000000..9a03e589
--- /dev/null
+++ b/docs/PERL
@@ -0,0 +1,491 @@
+
+ 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();
+
+A list of signals that irssi send can be found from SIGNALS file.
+
+
+ *** 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'.
+
+
+ *** 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_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 (FIXME: can't it return the hash table itself?!). 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::command_split(cmd, arg, max_nicks)
+  Split the `cmd' into several commands so `arg' argument has only
+  `max_nicks' number of nicks.
+
+  Example: $server->command_split("KICK nick1,nick2,nick3 :byebye", 1, 2);
+  Irssi will send commands "KICK nick1,nick2 :byebye" and
+  "KICK nick3 :byebye" to server.
+
+
+ *** Server functions
+
+Server::values()
+  Get some information about server. This function returns a reference to
+  hash table (FIXME: can't it return the hash table itself?!). Hash table
+  has keys:
+	"address" - Address where we connected (irc.blah.org)
+	"real_address" - Who the server thinks it is (irc1.blah.org)
+	"port" - Port where we connected
+	"tag" - Unique server tag.
+	"ircnet" - IRC network
+	"password" - Password we used in connection.
+
+	"nick" - Current nick
+	"wanted_nick" - Nick which we would prefer to use
+	"username" - User name
+	"realname" - Real name
+	"usermode" - Current user mode
+	"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 server_connect(address, [port=6667, [password='', [nick='']]])
+  Create new server connection.
+
+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_any(channel)
+  Find `channel' from any server
+
+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 (FIXME: can't it return the hash table itself?!). Hash table
+  has keys:
+	"name" - channel name
+	"type" - channel type ("channel", "query", "dcc chat", "empty")
+
+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 (FIXME: can't it return the hash table itself?!). 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 (FIXME: can't it return the hash table itself?!). Hash table
+  has keys:
+	"nick" - Plain nick
+	"host" - Host (blah@there.org)
+	"name" - Real name
+	"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.
+
+
+ *** Netsplits
+
+Netsplit::values()
+  Get some information about netsplit. This function returns a reference to
+  hash table (FIXME: can't it return the hash table itself?!). 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 (FIXME: can't it return the hash table itself?!). 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 (FIXME: can't it return the hash table itself?!). 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 (FIXME: can't it return the hash table itself?!). 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 (FIXME: can't it return the hash table itself?!). 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.
diff --git a/src/signal.doc b/docs/SIGNALS
index 1374f68e..715e8ebe 100644
--- a/src/signal.doc
+++ b/docs/SIGNALS
@@ -52,6 +52,9 @@ irc.c:
  "event "<cmd>, char *args, SERVER_REC, char *sender_nick, char *sender_address
  "default event", char *data, SERVER_REC, char *sender_nick, char *sender_address
 
+(for perl parser..)
+ "redir "<cmd>, char *args, SERVER_REC, char *sender_nick, char *sender_address
+
 lag.c:
 
  "server lag", SERVER_REC
diff --git a/src/Makefile.am b/src/Makefile.am
index c840f340..8558338a 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -18,5 +18,3 @@ noinst_HEADERS = \
 	irssi-plugin-gui.h
 
 SUBDIRS = irc-base irc-extra ui-common lib-config lib-nongui lib-popt settings $(GNOMEUI) $(TEXTUI) $(BOTUI)
-
-EXTRA_DIST = signal.doc