diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/Guide.pod | 52 | ||||
| -rw-r--r-- | docs/Irssi.pod | 42 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/Line.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/LineCache.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/LineInfo.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/MainWindow.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/StatusbarItem.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/TextBufferView.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/TextUI/Textbuffer.pod | 3 |
9 files changed, 110 insertions, 5 deletions
diff --git a/docs/Guide.pod b/docs/Guide.pod index 239aac7..eba0912 100644 --- a/docs/Guide.pod +++ b/docs/Guide.pod @@ -10,8 +10,19 @@ Guide To Irssi Scripting. =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 +B<TODO: Forgotten what was going to go here> + =head2 Loading Scripts are loaded via C</SCRIPT LOAD I<filename>>. A default Irssi @@ -22,7 +33,6 @@ 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 @@ -44,6 +54,12 @@ network connections or processes, and restore any Irssi modifications made. 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: @@ -111,8 +127,22 @@ 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 +B<TODO: Find the example code that demonstrates this> + =head2 If In Doubt, Dump! C<Data::Dumper> is an extremely good way to inspect Irssi internals if you're @@ -139,17 +169,29 @@ of their file. Whilst better than no documentation at all, a preferable approac is to allow that help to be accessed from within Irssi itself, using the C</HELP> command. -B<TODO: how> - +B<TODO: example - catch or rebind /HELP, then check args and either print and +sig_stop or continue> =head3 Use Tab Completion One of the great features of Irssi is the ability to complete commands, -subcommands and even certain arguments. +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. + + =head3 Use Settings for Customisation -B<TODO: why?> +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> diff --git a/docs/Irssi.pod b/docs/Irssi.pod index 97e4799..d67b9aa 100644 --- a/docs/Irssi.pod +++ b/docs/Irssi.pod @@ -404,6 +404,48 @@ using one of the C<settings_add> functions. =head4 C<settings_add_size $section, $key, $def> +Each of the above functions operates in the same way, but creates a different +data type. For each function, C<$section> is a string describing the +group the entry falls into, C<$key> is the name of the setting. The key must +be a single string, and typically multiple words are separated by underscores. + +The final parameter, C<$def>, is the default value of this setting. It should +correspond to the type of the setting being created. + +B<TODO: move this list to another section?> + +The following list summarises the data types available: + +=over + +=item C<str> + +A generic string type, which can contain arbitrary text. It is also commonly +used to build space-separated lists of entries. + +=item C<int> + +An integer type. Integers must be whole numbers, but may also be negative or zero. + +=item C<bool> + +A boolean type. In Perl terms, values are C<0> for false, and anything else for +true. When acting on them externally, C<ON> and C<OFF> are the usual terms used. + +=item C<time> + +A time type. B<TODO: what values can it take?> + +=item C<level> + +An irssi Messagelevel. See C</HELP LEVELS> for a full list and description. + +=item C<size> + +B<TODO: What is this for?> + +=back + =head3 Retrieving Settings =head4 C<settings_get_str $key> diff --git a/docs/Irssi/TextUI/Line.pod b/docs/Irssi/TextUI/Line.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/Line.pod +++ b/docs/Irssi/TextUI/Line.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/LineCache.pod b/docs/Irssi/TextUI/LineCache.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/LineCache.pod +++ b/docs/Irssi/TextUI/LineCache.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/LineInfo.pod b/docs/Irssi/TextUI/LineInfo.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/LineInfo.pod +++ b/docs/Irssi/TextUI/LineInfo.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/MainWindow.pod b/docs/Irssi/TextUI/MainWindow.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/MainWindow.pod +++ b/docs/Irssi/TextUI/MainWindow.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/StatusbarItem.pod b/docs/Irssi/TextUI/StatusbarItem.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/StatusbarItem.pod +++ b/docs/Irssi/TextUI/StatusbarItem.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/TextBufferView.pod b/docs/Irssi/TextUI/TextBufferView.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/TextBufferView.pod +++ b/docs/Irssi/TextUI/TextBufferView.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty diff --git a/docs/Irssi/TextUI/Textbuffer.pod b/docs/Irssi/TextUI/Textbuffer.pod index e69de29..08bdae1 100644 --- a/docs/Irssi/TextUI/Textbuffer.pod +++ b/docs/Irssi/TextUI/Textbuffer.pod @@ -0,0 +1,3 @@ +__END__ + +=head1 Empty |