diff options
Diffstat (limited to 'docs/General/Guide.pod')
| -rw-r--r-- | docs/General/Guide.pod | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/docs/General/Guide.pod b/docs/General/Guide.pod new file mode 100644 index 0000000..3a9f43f --- /dev/null +++ b/docs/General/Guide.pod @@ -0,0 +1,346 @@ +__END__ + +=head1 NAME + +Guide To Irssi Scripting. + +=head1 DESCRIPTION + +=head1 LOADING AND UNLOADING SCRIPTS + +=head2 File Locations + +Packaged Irssi script files are usually placed in F</usr/share/irssi/scripts/>, +but custom scripts or those required by a single user can be placed in +F<~/.irssi/scripts/>. + +=head3 Autorunning Scripts + +If you require a script be run when Irssi starts, you can place the file (or +better, create a symlink to it) into F<~/.irssi/scripts/autorun/>. + +=head2 Testing + +=for comment B<TODO: Forgotten what was going to go here> + +=head3 C</SCRIPT EXEC> + +B<TODO: Using it for testing stuff out> + +B<TODO: Also for very short scripts (with -permanent?)> + +B<TODO: Quoting rules for vars and things?> + +=head2 Loading + +Scripts are loaded via C</SCRIPT LOAD I<filename>>. A default Irssi +configuration also provides the C</RUN> alias as an alternative to C</SCRIPT +LOAD>. + +Loaded scripts will exist in the Irssi namespace as: +C<Irssi::Script::I<E<lt>nameE<gt>>>, where I<name> is the filename stripped of its +F<.pl> extension. + +=head2 Unloading + +A script can be unloaded via the C</SCRIPT UNLOAD I<name>> command. The name is +typically the script filename without the F<.pl> extension, so F<nickcolor.pl> +becomes C</SCRIPT UNLOAD nickcolor>. + +As part of the unloading process, if the script contains a + + sub UNLOAD { + ... + } + +function, it will be run just before the script is unloaded and all variables +destroyed. This can be used to clean up any temporary files, shut down any +network connections or processes, and restore any Irssi modifications made. + +=head1 ANATOMY OF A SCRIPT + +In this section, we develop a very simplistic script and look at the +necessary code. + +B<Note:> This section has considerable overlap with L<Juerd's Scripting +Tutorial|http://juerd.nl/site.plp/irssiscripttut>, which you may also +wish to read. + +B<TODO: Figure out a basic script to use as an example> + +=head2 Preamble + +All scripts should contain a header as follows: + + use strict; + use warnings; + + use vars qw($VERSION %IRSSI); + use Irssi; + + $VERSION = '1.00'; + %IRSSI = ( + authors => 'Author Name(s)', + contact => 'author_email@example.com', + name => 'Script Title', + description => 'Longer script description ', + license => 'Public Domain', + ); + +The first two lines should be used in B<all> perl scripts, not just Irssi. They +provide far greater error checking and diagnostics should you make a mistake in your +code. + +The C<use vars qw($VERSION %IRSSI)> defines two global variables, which are then +set below to the appropriate values. + +C<use Irssi> tells the script to make the various L<Irssi> support functions available. +Additional parameters passed here with C<qw/.../> can be used to import functions into +the current script namespace. + + +=head1 COMMONLY SCRIPTED TASKS + +=head2 Modifying an input line before sending + +B<TODO: catch "send text", modify it if necessary, signal_emit it> + +=head2 Responding to a public message + +B<TODO: catch "messsage public", check params, generate response> + +=head2 Responding to a private message + +B<TODO: catch "messsage private", check params, generate response> + +=head1 USEFUL THINGS + + +=head2 Dealing with Blocking IO + +B<TODO: see F<hddtemp.pl> on SIO> - fork and use pipes to communicate. Also +remember to pidwait the child> + + +=head2 Getting the Response Value of a Remote Command + +B<TODO: Add bazerka's snippet here> + +=head2 Getting the Response Value of a Local Command + +B<TODO: How?!??> + +There is no simple way to achieve this. The data backing most common activities +can be extracted through other API calls, but there are some exceptions. + +Maybe, look up the format, intercept gui print text, try to match it against +what you're expecting? + +Can this be generalised at all? + +=head2 Sharing Code Between Scripts + +There are 2 main ways for scripts to communicate, either via emitting and +handling Irssi signals, or by calling functions from one another directly. + +=head3 Using Signals + +In order to use custom signals, they must first be registered with Irssi. +During registration, a list of the parameters must also be specified. Once specified, +it cannot be changed without restarting Irssi, so be warned. + +After registration, your script can simply listen for signals with +L<Irssi::signal_add|Irssi/signal_add $sig_name, $func>, or generate them for +others to handle with L<Irssi::signal_emit|Irssi/signal_emit $sig_name, @params> + +For example: + +B<TODO: Example here> + +=head3 Using Functions + +Because scripts exist in a well-defined namespace of C<Irssi::Script::SOMEPACKAGE>, +it is possible to manipulate the perl symbol table to call functions directly on them, +assuming they are loaded. + +Because the following code depends on I<symbolic references>, it is necessary to +tell Perl to allow them, despite normally being prohibited by C<use strict>. +The C<no strict 'refs';> line takes care of this, and reenables them at the end +of the snippet. + + no strict 'refs'; + if (defined %{ 'Irssi::Script::SOMEPACKAGE::' }) { + if (defined &{'Irssi::Script::SOMEPACKAGE::SOME_FUNC'} ) { + (&{'Irssi::Script::SOMEPAKAGE::SOME_FUNC'}(@args)); + } else { + print("Err: can't find Irssi::Script::SOMEPACKAGE::SOME_FUNC"); + } + } + use strict 'refs'; + +Here, C<SOMEPACKAGE> is the name of the script package which contains the +function you want to call, and C<SOME_FUNC> is the name of the function within +it you wish to call. The first 2 C<defined(..)> lines take care of ensuring +that the package and function exist, and generate an error otherwise. Other +error handling is possible, including executing a C</SCRIPT LOAD> to load the +necessary script and retry, but is not shown here. + +I<This snippet was provided by C<Bazerka> on Freenode/#irssi>. + +=head2 If In Doubt, Dump! + +C<Data::Dumper> is an extremely good way to inspect Irssi internals if you're +looking for an undocumented feature. + +The C<DUMP> alias by L<Wouter +Coekaerts|http://wouter.coekaerts.be/site/irssi/aliases> provides an easy way to +check object fields. + +Dump perl object (e.g. C</dump Irssi::active_win>): + + /alias DUMP script exec use Data::Dumper\; print Data::Dumper->new([\\$0-])->Dump + +=head2 Making Scripts Act Native + +An important part of creating a good script is to make it behave as though it +were a part of Irssi. Adhering to some of the standard conventions can make this +easier. + +=head3 Provide Help + +Scripts commonly store information about how to use them in comments at the top +of their file. Whilst better than no documentation at all, a preferable approach +is to allow that help to be accessed from within Irssi itself, using the C</HELP> +command. + + my $help = "this is help for b"; + + Irssi::command_bind('help', sub { + if ($_[0] eq 'test_b') { + Irssi::print($help, MSGLEVEL_CLIENTCRAP); + Irssi::signal_stop; + } + } + ); + +This example demonstrates overriding the C</HELP> command, and if the argument +matches our command, print some custom help and prevent the internal Irssi help +function from being called. Otherwise, it falls back to the default help. + + +I<This snippet was provided by C<culb> on Freenode/#irssi>. + +=head3 Use Tab Completion + +One of the great features of Irssi is the ability to complete commands, +subcommands and even certain arguments. Using the subcommands processing feature +described below automatically allows those subcommands to be tab-completed, but +for more complex tasks, you can hook into the autocompletion system itself. + +In order to create your own completions, you must intercept the C<"complete +word"> signal and return a list of completion candidates. + + sub do_complete { + my ($strings, $window, $word, $linestart, $want_space) = @_; + + # only provide these completions if the input line is otherwise empty. + return unless ($linestart eq '' && $word eq ''); + + # add the completion candidates + push @$strings, qw/foo bar baz bacon/; + + # indicate that we want to include a space after the completion + $$want_space = 1; + + # prevent internal Irssi completion from responding + Irssi::signal_stop; + } + + Irssi::signal_add_first('complete word', \&do_complete); + +I<This snippet taken from +L<F<complete_lastspoke.pl>|http://scripts.irssi.org/scripts/complete_lastspoke.pl> +by Daenyth> + +=head3 Use Settings for Customisation + +Many scripts require the setting of various parameters to affect how they behave. +One approach is to require the user to directly edit the script file, but this +is less than ideal for a number of reasons. Firstly, it is easy to introduce +errors into a script by accidentally deleting closing quotes or semicolons. +Secondly, it has no effect until the script is reloaded, leading to confusion. + +A much better alternative is to use Irssi's inbuilt settings mechanism to allow +users to set these parameters from within Irssi, as well as to C</SAVE> their +settings for subsequent invocations. + +B<TODO: different types of settings> + +B<TODO: register/set/get> + +B<TODO: Listening for changes and acting accordingly> + +=head3 Use Subcommands to Group Script Functionality + +A common theme in Irssi scripts is to define commands with a prefix, such as +C</myscript_foo>, C<myscript_bar>, etc. This helps to avoid accidentally clobbering +native commands and those defined by other scripts, but is a problem better solved +with I<subcommands>. + +Subcommands allow you to bind commands such as C</myscript foo> and C</myscript bar>. +Completions are automatically handled for both the primary command, and any +subcommands contained within it. + +The following example demonstrates how to use subcommands from within a script: + + Irssi::command_bind("foo bar", \&subcmd_bar); + Irssi::command_bind("foo", \&subcmd_handler); + + sub subcmd_handler { + my ($data, $server, $item) = @_; + $data =~ s/\s+$//g; # strip trailing whitespace. + Irssi::command_runsub('foo', $data, $server, $item); + } + + sub subcmd_bar { + my ($args) = @_; + print "subcommand called with: $args"; + } + +=head1 AUTHOR & THANKS + +This page was written by Tom Feist C<shabble+irssi@metavore.org>, but draws +on the help of many many people. + +The denizens of Freenode/#irssi have been particularly helpful, especially +C<Bazerka> and C<culb>. + +To report bugs or suggestions, email me at the address before, or come talk to +me in C<#irssi> on C<irc.freenode.net>. + +=head1 OTHER RESOURCES + +The documentation assembled here and elsewhere on this site has been drawn from +many different places, and a lot of valuable information is available from the +following sites. + + +=over + +=item L<http://irssi.org/documentation/perl> + +=item L<http://irssi.org/documentation/signals> + +=item L<http://irssi.org/documentation/special_vars> + +=item L<http://irssi.org/documentation/formats> + +=item L<http://irssi.org/documentation/settings> + +=item L<http://juerd.nl/site.plp/irssiscripttut> + +=item L<http://irchelp.org/irchelp/rfc/rfc.html> + +=item L<http://wouter.coekaerts.be/site/irssi/irssi> + +=back |