From 3d513eebfad1c55c76da5b7a26c59d7b20eabd50 Mon Sep 17 00:00:00 2001 From: Timo Sirainen Date: Thu, 24 Feb 2000 23:43:49 +0000 Subject: [PATCH] Perl documentation and updates git-svn-id: http://svn.irssi.org/repos/irssi/trunk@129 dbcabf3a-b0e7-0310-adc4-f8d773084564 --- NEWS | 22 +- docs/Makefile.am | 2 + docs/PERL | 491 +++++++++++++++++++++++++++++++++ src/signal.doc => docs/SIGNALS | 3 + src/Makefile.am | 2 - 5 files changed, 517 insertions(+), 3 deletions(-) create mode 100644 docs/PERL rename src/signal.doc => docs/SIGNALS (98%) 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 [stable] +v0.7.27 2000-02-26 Timo Sirainen + + * 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 + + - + +v0.7.25 2000-02-19 Timo Sirainen + /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 similarity index 98% rename from src/signal.doc rename to docs/SIGNALS index 1374f68e..715e8ebe 100644 --- a/src/signal.doc +++ b/docs/SIGNALS @@ -52,6 +52,9 @@ irc.c: "event ", 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 ", 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