diff options
Diffstat (limited to 'docs/General/Guide.pod')
| -rw-r--r-- | docs/General/Guide.pod | 370 |
1 files changed, 0 insertions, 370 deletions
diff --git a/docs/General/Guide.pod b/docs/General/Guide.pod deleted file mode 100644 index a3cfe38..0000000 --- a/docs/General/Guide.pod +++ /dev/null @@ -1,370 +0,0 @@ -__END__ - -=head1 NAME - -Guide To Irssi Scripting. - -=head1 DESCRIPTION - -This page presents a bunch of additional information about scripting for Irssi -that doesn't fit well anywhere else. It contains useful tips, common pitfalls, -and a bunch of other handy things. At least, I hope so. - -=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/>. - -Alternatively, if you want more control over the order in which scripts are -autoloaded, you can place - - SCRIPT LOAD script1 - SCRIPT LOAD script2 - SCRIPT LOAD script3 - -into your F<~/.irssi/startup> file. - -I<This tip was provided by C<Rhonda> on Freenode/#irssi>. - -=head2 Testing - -=for comment B<TODO: Forgotten what was going to go here> - -=head3 C</SCRIPT EXEC> - -The C<SCRIPT EZEC> command allows you to test various simple ideas straight from -the Irssi interface. It can also be used to register signal handlers and -commands if run with the C<-permanent> option. - -B<NB: C<-permanent> only means that the script should not terminate -immediately. It is still not persistent between restarts of the Irssi client. -Truly permanent scripts should be placed in autorun scripts or added to -F<~/.irssi/startup>> - - -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 are optional, but strongly advised. 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 |