From d974da559601a1c95740a01d72ce2ee91008354e Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Fri, 22 Apr 2011 03:23:07 +0100 Subject: removed docs/ from dev branch, since they're all in their own repo (well, wiki) by now. --- docs/Irssi.pod | 1109 -------------------------------------------------------- 1 file changed, 1109 deletions(-) delete mode 100644 docs/Irssi.pod (limited to 'docs/Irssi.pod') diff --git a/docs/Irssi.pod b/docs/Irssi.pod deleted file mode 100644 index f5d72b7..0000000 --- a/docs/Irssi.pod +++ /dev/null @@ -1,1109 +0,0 @@ -__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