aboutsummaryrefslogtreecommitdiffstats
path: root/docs/Irssi
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/Irssi.pm286
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>