diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/Irssi.pm | 286 |
1 files changed, 285 insertions, 1 deletions
diff --git a/docs/Irssi.pm b/docs/Irssi.pm index c52fbc5..263d124 100644 --- a/docs/Irssi.pm +++ b/docs/Irssi.pm @@ -2,6 +2,8 @@ __END__ =head1 NAME +Irssi.pm + =head1 DESCRIPTION =head1 CLASSES @@ -14,23 +16,182 @@ __END__ =item C<Irssi::active_win> -- returns the currently active L<Irssi::Window> object. +=item Window active_win() - return active window + +=item Server active_server() - return server in active window + +=item windows() - return list of all windows +=item servers() - return list of all servers +=item reconnects() - return list of all server reconnections +=item channels() - return list of all channels + +=item queries() - return list of all queries + +=item commands() - return list of all commands + +=item logs() - return list of all log files + +=item ignores() - returns list of all ignores + =back + =head2 Signals +Irssi is pretty much based on sending and handling different signals. +Like when you receive a message from server, say: + +C<:nick!user@there.org PRIVMSG you :blahblah> + +Irssi will first send a signal: + +C<"server incoming", SERVER_REC, "nick!user@there PRIVMSG ..."> + +You probably don't want to use this signal. Default handler for this +signal interprets the header and sends a signal: + +C<"server event", SERVER_REC, "PRIVMSG ...", "nick", "user@there.org"> + +You probably don't want to use this either, since this signal's default +handler parses the event string and sends a signal: + +C<"event privmsg", SERVER_REC, "you :blahblah", "nick", "user@there.org"> + +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 calling +L<Irssi::signal_stop()|Irssi/signal_stop> + +For example: + + sub event_privmsg { + # $data = "nick/#channel :text" + my ($server, $data, $nick, $address) = @_; + my ($target, $text) = split(/ :/, $data, 2); + + Irssi::signal_stop() if ($text =~ /free.*porn/ || $nick =~ /idiot/); + } + + Irssi::signal_add("event privmsg", "event_privmsg"); + +This will hide all public or private messages that match the regexp +C<"free.*porn"> or the sender's nick contain the word "idiot". Yes, you +could use /IGNORE instead for both of these C<:)> + +You can also use L<C<signal_add_last()>|/signal_add_last> if you wish to let the +Irssi's internal functions be run before yours. + +A list of signals that irssi sends can be found in the L<Signals> documentation. + + + + =head3 Handling Signals +=head4 C<signal_add($sig_name, $func)> + +Bind C<$sig_name>' to function C<$func>. The C<$func> argument may be either +a string containing the name of a function to call, or a coderef. + +For example: + + Irssi::signal_add("default command", sub { ... }); + + Irssi::signal_add("default command", "my_function"); + + Irssi::signal_add("default command", \&my_function); + +In all cases, the specified function will be passed arguments in C<@_> as specified +in L<Signals>. + +=head4 C<signal_add_first($sig_name, $func)> + +Bind `signal' to function `func'. Call `func' as soon as possible. + +=head4 C<signal_add_last(signal, func)> + +Bind `signal' to function `func'. Call `func' as late as possible. + +=head4 C<signal_remove(signal, func)> + +Unbind `signal' from function `func'. + =head3 Controlling Signal Propagation +=head4 C<signal_emit(signal, ...)> + +Send signal `signal'. You can give 6 parameters at maximum. + +=head4 C<signal_continue(...)> + +Continue currently emitted signal with different parameters. + +=head4 C<signal_stop()> + +Stop the signal that's currently being emitted. + +=head4 C<signal_stop_by_name(signal)> + +Stop the signal with name `signal' that's currently being emitted. + =head3 Registering New Signals +=head4 C<signal_register(%hashref)> + +Register parameter types for one or more signals. +C<%hash> must map one or more signal names to references to arrays +containing 0 to 6 type names. Some recognized type names include +int for integers, intptr for references to integers and string for +strings. For all standard signals see src/perl/perl-signals-list.h +in the source code (this is generated by src/perl/get-signals.pl). + +For example: + my $signal_config_hash = { "new signal" => [ qw/string string integer/ ] }; + Irssi::signal_register($signal_config_hash); +Any signals that were already registered are unaffected. + +B<Signals are not persistent.> Once registered, a signal cannot be unregistered without +restarting Irssi. B<TODO: True?>, including modifying the type signature. + +Registration is required to get any parameters to signals written in +Perl and to emit and continue signals from Perl. =head2 Commands +See also L<Irssi::Command> + +command_bind(cmd, func[, category]) + Bind command `cmd' to call function `func'. `category' is the + category where the command is displayed in /HELP. + +command_runsub(cmd, data, server, item) + Run subcommands for `cmd'. First word in `data' is parsed as + subcommand. `server' is Irssi::Server rec for current + Irssi::Windowitem `item'. + + Call command_runsub in handler function for `cmd' and bind + with command_bind("`cmd' `subcmd'", subcmdfunc[, category]); + +command_unbind(cmd, func) + Unbind command `cmd' from function `func'. + +command_set_options(cmd, data) + Set options for command `cmd' to `data'. `data' is a string of + space separated words which specify the options. Each word can be + optionally prefixed with one of the following character: + + '-': optional argument + '+': argument required + '@': optional numeric argument + +command_parse_options(cmd, data) + Parse options for command `cmd' in `data'. It returns a reference to + an hash table with the options and a string with the remaining part + of `data'. On error it returns the undefined value. + =head3 Registering Commands =head3 Invoking Commands @@ -41,12 +202,135 @@ __END__ =head2 Settings + =head3 Creating New Settings +=head4 C<settings_add_str(section, key, def)> + +=head4 C<settings_add_int(section, key, def)> + +=head4 C<settings_add_bool(section, key, def)> + +=head4 C<settings_add_time(section, key, def)> + +=head4 C<settings_add_level(section, key, def)> + +=head4 C<settings_add_size(section, key, def)> + + =head3 Retrieving Settings +=head4 C<settings_get_str($key)> + +=head4 C<settings_get_int($key)> + +=head4 C<settings_get_bool($key)> + +=head4 C<settings_get_time($key)> + +=head4 C<settings_get_level($key)> + +=head4 C<settings_get_size($key)> + =head3 Modifying Settings +Set value for setting. + +B<If you change the settings of another module/script with one of these, you +must emit a C<"setup changed"> signal afterwards.> + +=head4 C<settings_set_str(key, value)> + +=head4 C<settings_set_int(key, value)> + +=head4 C<settings_set_bool(key, value)> + +=head4 C<settings_set_time(key, value)> + +=head4 C<settings_set_level(key, value)> + +=head4 C<settings_set_size(key, value)> + +=head4 C<settings_remove(key)> + +Remove a setting. + + +=head2 IO and Process Management + +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_add_once(msecs, func, data); + Call `func' once after `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. + +input_add(source, condition, func, data) + Call `func' with parameter `data' when specified IO happens. + `source' is the file handle that is being listened. `condition' can + be INPUT_READ, INPUT_WRITE or both. Returns tag which can be used to + remove the listener. + +input_remove(tag) + Remove listener with tag. + +pidwait_add(pid) + Adds `pid' to the list of processes to wait for. The pid must identify + a child process of the irssi process. When the process terminates, a + "pidwait" signal will be sent with the pid and the status from + waitpid(). This is useful to avoid zombies if your script forks. + +pidwait_remove(pid) + Removes `pid' from the list of processes to wait for. Terminated + processes are removed automatically, so it is usually not necessary + to call this function. + + + +=head2 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. + + +=head2 Themes + +You can have user configurable texts in scripts that work just like +irssi's internal texts that can be changed in themes. + +First you'll have to register the formats: + +Irssi::theme_register([ + 'format_name', '{hilight my perl format!}', + 'format2', 'testing.. nick = $0, channel = $1' +]); + +Printing happens with one of the functions: + +printformat(level, format, ...) +Window::printformat(level, format, ...) +Server::printformat(target, level, format, ...) +Windowitem::printformat(level, format, ...) + +For example: + + $channel->printformat(MSGLEVEL_CRAP, 'format2', + 'nick', $channel->{name}); + +=head1 COPYRIGHT +All the content of this site is copyright © 2000-2010 The Irssi project. -=head2 blahblah +Formatting to POD and linking by Tom Feist + L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org> |