__END__ =head1 NAME Irssi =head1 DESCRIPTION L is a console based fullscreen IRC client. It is written in the C programming language, and can be modified through both I -- dynamically loadable compiled libraries -- and I, written in L. Modules are not covered in this documentation, other than to note that Perl scripting support itself may be compiled as a module rather than built directly into Irssi. The C command can be used from within Irssi to check if Perl support is available. If not, refer to the F file for how to recompile irssi. The C package is the basis of Perl scripting in Irssi. It does not export any functions by default, and requires that all function-calls be fully qualified with the C> prefix. See L for alternatives. =head1 CLASSES This documentation has been split into a number of pages, each documenting a particular class or pseudo-class. The following list contains all of these additional pages. B =over 4 =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =item L =back =head1 EXPORTS Nothing by default, but passing a list of function names when Cing the module will import them into the current namespace. For example: use Irssi qw/signal_emit signal_add .../; =head1 METHODS =head2 Accessors =head3 C C returns the currently active L =head3 C C returns the currently active L in active window. =head3 C C returns a list of all L. When called in scalar context C, only the first window is returned. =head3 C returns a list of all L. =head3 C returns a list of all L. =head3 C returns a list of all L. =head3 C returns a list of all L. =head3 C returns a list of all L. =head3 C returns a list of all L. =head3 C returns a list of all L. =head2 File Accessors =head3 C Indicates if Irssi has been started with a GUI frontend. Return values are: =over =item C - C<0> =item C - C<1> =item C - C<2> =item C - C<3> =item C - C<4> =item C - C<5> =back The symbolic constants listed above can be accessed from scripts as follows: my $is_text = Irssi::get_gui == Irssi::IRSSI_GUI_TEXT; =head3 C Returns a string containing the absolute location of the binary that this instance of Irssi was invoked from. =head3 C Returns a string containing the absolute location of the config file that was specified or defaulted to when Irssi started up. Can be modified at startup using the C<--config=> commandline option, or defaults to F<~/.irssi/config>. =head3 C Returns a string containing the absolute location of the base directory that was specified or defaulted to when Irssi started up. Can be modified at startup using the C<--home=> commandline option, or defaults to F<~/.irssi/>. =head2 Signals See also L 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", Irssi::Server, "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", Irssi::Server, "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 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 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 documentation. =head3 Handling Signals =head4 C 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. =head4 C Bind C<$sig_name> to function C<$func>. Call C<$func> as soon as possible when the signal is raised. =head4 C Bind C<$sig_name> to function C<$func>. Call C<$func> as late as possible (after all other signal handlers). =head4 C Unbind C<$sig_name> from function C<$func>. B coderef? What happens?> =head3 Controlling Signal Propagation =head4 C Send a signal of type C<$sig_name>. Up to 6 parameters can be passed in C<@params>. =head4 C Propagate a currently emitted signal, but with different parameters. This only needs to be called if you wish to change them, otherwise all subsequent handlers will be invoked as normal. For example, we can intercept a public message and rewrite the content before passing it on: Irssi::signal_add_first 'message public', sub { my ($server, $msg, @rest) = @_; $msg =~ s/this/that/g; Irssi::signal_continue($server, $msg, @rest); }; Note that if you want to do this sort of rewriting, it is important to add your handler using L to it is called before the internal Irssi handlers which would usually consume it. B =head4 C Stop the signal that's currently being emitted, no other handlers after this one will be called. =head4 C Stop the signal with name C<$sig_name> that is currently being emitted. =head3 Registering New Signals =head4 C Register parameter types for one or more signals. C<$hashref> 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 F in the source code (this is generated by F). 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 Once registered, a signal cannot be unregistered without restarting Irssi. B, 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. B =head2 Commands See also L =head3 Registering Commands =head4 C Bind a command string C<$cmd> to call function C<$func>. C<$func> can be either a string or coderef. C<$category> is an optional string specifying the category to display the command in when C is used. When a command is invoked, either by the user typing C, the handler function will be called. It will receive the following parameters, passed in C<@_>: my ($argument_string, $server_obj, $window_item_obj) = @_; The argument string must be processed by the handler to split it into individual words if necessary. The L function can be used to process options (beginning with a single dash), and will also return the remainder of the string to be processed as desired. =head4 C Run subcommands for C<$cmd>. First word in C<$data> is parsed as subcommand. C<$server> is L record for current L C<$item>. Call command_runsub in handler function for C<$cmd> and bind with: command_bind("$cmd $subcmd", subcmdfunc[, category]); See the L for further details. =head4 C Unbind command C<$cmd> from function C<$func>. =head3 Invoking Commands =head4 C Run the command specified in C<$string> in the currently active context. B vs concatenating into the command string?> See also L =head3 Parsing Command Arguments =head4 C Set options for command C<$cmd> to C<$data>. C<$data> is a string of space separated words which specify the options. Each word can be optionally prefixed with one of the following character: =over 16 =item C<->: optional argument =item C<@>: optional numeric argument =item C<+>: required argument =back For example: my $argument_format = "+something -other -another @number"; Irssi::command_set_options('mycmd', $argument_format); Thus, the command may be run as C. =head4 C Parse out options as specified by L for command C<$cmd>. A string containing the input received by the command handler should be passed in as C<$data>. The return value is either C if an error occurred, or a list containing two items. The first is a hashref mapping the option names to their values. Optional arguments which were not present in the input will not be included in the hash. The second item in the return list is a string containing the remainder of the input after the arguments have been parsed out. For example: sub my_cmd_handler { my ($command_args) = @_; my @options_list = Irssi::command_parse_options "my_cmd", $command_args; if (@options_list) { my $options = $options_list->[0]; my $arg_remainder = $options_list->[1]; if (exists $options->{other} && $options->{something} eq 'hello') { ... } } } =head2 Settings Settings are a way to permanently store values that your script may wish to use. They are also easily manipulable by the user through the C command, making them a good way to allow configuration of your script. The following list summarises the data types available: =over =item C A generic string type, which can contain arbitrary text. It is also commonly used to build space-separated lists of entries. =item C An integer type. Integers must be whole numbers, but may also be negative or zero. It is stored internally as a C, and has a range of +/- 2^31. =item C A boolean type. In Perl terms, values are C<0> for false, and anything else for true. When acting on them externally, C and C are the usual terms used. =item C