From c2252b6c67df64995b336c27fb175d504af20675 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Wed, 21 Jul 2010 17:25:07 +0100 Subject: added some stuff to the guide, and cleaned up some irssi.pod function descs --- docs/Guide.pod | 54 +++++++++++++++++++++++- docs/Irssi.pod | 51 ++++++++++++++++------- docs/Irssi/Ignore.pod | 1 + docs/Irssi/Irc.pod | 27 ++++++++++++ docs/Irssi/Irc/Ban.pod | 4 +- docs/Irssi/Irc/Client.pod | 5 ++- docs/Irssi/Irc/Dcc.pod | 2 +- docs/Irssi/Irc/Notifylist.pod | 8 ++-- docs/Irssi/UI/Window.pod | 96 ++++++++++++++++++++++++++----------------- docs/Irssi/Windowitem.pod | 3 ++ docs/Signals.pod | 20 ++++----- 11 files changed, 200 insertions(+), 71 deletions(-) create mode 100644 docs/Irssi/Irc.pod (limited to 'docs') diff --git a/docs/Guide.pod b/docs/Guide.pod index 4f78fc0..239aac7 100644 --- a/docs/Guide.pod +++ b/docs/Guide.pod @@ -18,6 +18,10 @@ Scripts are loaded via C>. A default Irssi configuration also provides the C alias as an alternative to C. +Loaded scripts will exist in the Irssi namespace as: +CnameE>>, where I is the filename stripped of its +F<.pl> extension. + =head2 Unloading @@ -42,16 +46,64 @@ necessary code. =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 perl scripts, not just Irssi. They +provide far greater error checking and diagnostics should you make a mistake in your +code. + +The C defines two global variables, which are then +set below to the appropriate values. + +C tells the script to make the various L support functions available. + + + =head1 COMMONLY SCRIPTED TASKS =head2 Modifying an input line before sending +B + =head2 Responding to a public message +B + =head2 Responding to a private message +B + =head1 USEFUL THINGS + +=head2 Getting the Response Value of a Remote Command + +B + +=head2 Getting the Response Value of a Local Command + +B + +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 @@ -121,7 +173,7 @@ The following example demonstrates how to use subcommands from within a script: sub subcmd_handler { my ($data, $server, $item) = @_; - $data =~ s/\s+$//g; + $data =~ s/\s+$//g; # strip trailing whitespace. Irssi::command_runsub('foo', $data, $server, $item); } diff --git a/docs/Irssi.pod b/docs/Irssi.pod index fc7e81f..97e4799 100644 --- a/docs/Irssi.pod +++ b/docs/Irssi.pod @@ -27,6 +27,8 @@ 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 @@ -131,6 +133,7 @@ returns a list of all L. =head3 C +B returns a list of all L =head2 Signals @@ -282,6 +285,20 @@ 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 `cmd'. First word in `data' is parsed as @@ -291,7 +308,8 @@ L `item'. Call command_runsub in handler function for `cmd' and bind with command_bind("`cmd' `subcmd'", subcmdfunc[, category]); -B +See the L for +further details. =head4 C @@ -365,40 +383,43 @@ For example: =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. =head3 Creating New Settings -=head4 C +If a setting does not currently exist, it must first be registered with Irssi +using one of the C functions. -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C +=head4 C =head3 Retrieving Settings -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C -=head4 C +=head4 C =head3 Modifying Settings -Set value for setting. - B signal afterwards.> diff --git a/docs/Irssi/Ignore.pod b/docs/Irssi/Ignore.pod index 108c0ba..f93cbe3 100644 --- a/docs/Irssi/Ignore.pod +++ b/docs/Irssi/Ignore.pod @@ -7,6 +7,7 @@ Irssi::Ignore =head1 FIELDS Ignore->{} + mask - Ignore mask servertag - Ignore only in server channels - Ignore only in channels (list of names) diff --git a/docs/Irssi/Irc.pod b/docs/Irssi/Irc.pod new file mode 100644 index 0000000..e51b190 --- /dev/null +++ b/docs/Irssi/Irc.pod @@ -0,0 +1,27 @@ +__END__ + +=head1 NAME + +Irssi::Irc + +=head1 DESCRIPTION + +=head1 CLASSES + +=head1 EXPORTS + +=head1 METHODS + +=head2 Accessors + +=head3 C + +returns a list of all L + +=head1 COPYRIGHT + +All the content of this site is copyright E 2000-2010 L. + +Formatting to POD and linking by Tom Feist + L diff --git a/docs/Irssi/Irc/Ban.pod b/docs/Irssi/Irc/Ban.pod index ba8381f..7026ca1 100644 --- a/docs/Irssi/Irc/Ban.pod +++ b/docs/Irssi/Irc/Ban.pod @@ -2,14 +2,14 @@ __END__ =head1 NAME -Irssi::Ban +Irssi::Irc::Ban =head1 FIELDS Ban->{} + ban - The ban setby - Nick of who set the ban time - Timestamp when ban was set - =head1 METHODS diff --git a/docs/Irssi/Irc/Client.pod b/docs/Irssi/Irc/Client.pod index e07bed7..e0a27f4 100644 --- a/docs/Irssi/Irc/Client.pod +++ b/docs/Irssi/Irc/Client.pod @@ -2,10 +2,12 @@ __END__ =head1 NAME -Irssi::Client +Irssi::Irc::Client =head1 FIELDS + Client->{} + nick - nick of the client host - host of the client proxy_address - address of the proxy server @@ -16,5 +18,4 @@ Client->{} want_ctcp - whether the client wants to receive CTCPs ircnet - network tag of the network we proxy - =head1 METHODS diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod index d7ab4a3..5950a92 100644 --- a/docs/Irssi/Irc/Dcc.pod +++ b/docs/Irssi/Irc/Dcc.pod @@ -2,7 +2,7 @@ __END__ =head1 NAME -Irssi::Dcc +Irssi::Irc::Dcc =head1 FIELDS diff --git a/docs/Irssi/Irc/Notifylist.pod b/docs/Irssi/Irc/Notifylist.pod index 5b2628a..fd933ef 100644 --- a/docs/Irssi/Irc/Notifylist.pod +++ b/docs/Irssi/Irc/Notifylist.pod @@ -2,11 +2,12 @@ __END__ =head1 NAME -Irssi::Notifylist +Irssi::Irc::Notifylist =head1 FIELDS Notifylist->{} + mask - Notify nick mask away_check - Notify away status changes idle_check_time - Notify when idle time is reset and idle was bigger @@ -16,6 +17,7 @@ Notifylist->{} =head1 METHODS -Notifylist::ircnets_match(ircnet) - Returns 1 if notify is checked in `ircnet'. +=head2 C + +Returns 1 if notify is checked in `ircnet'. diff --git a/docs/Irssi/UI/Window.pod b/docs/Irssi/UI/Window.pod index a00827e..aa601a8 100644 --- a/docs/Irssi/UI/Window.pod +++ b/docs/Irssi/UI/Window.pod @@ -6,7 +6,8 @@ Irssi::UI::Window =head1 FIELDS -UI::Window->{} +C{}> + refnum - Reference number name - Name @@ -33,7 +34,8 @@ UI::Window->{} theme_name - Active theme in window, undef = default -UI::TextDest->{} +C{}> + window - Window where the text will be written server - Target server target - Target channel/query/etc name @@ -45,72 +47,92 @@ UI::TextDest->{} =head1 METHODS -Window::command(cmd) -Window::print(str[, level]) +=head2 C +=head2 C -Window::items() - Return a list of items in window. +=head2 C + +Return a list of items in window. -Window -window_create(automatic) -Windowitem::window_create(automatic) - Create a new window. -Window::destroy() - Destroy the window. +=head2 C + +=head2 C + +Destroy the window. Irssi::Window Windowitem::window() Returns parent window for window item. -Window -window_find_name(name) - Find window with name. +=head2 C -Window -window_find_refnum(refnum) - Find window with reference number. +Find window with name.L + +=head2 C + +Find window with reference number. Window window_find_level(level) + Server::window_find_level(level) Find window with level. Window window_find_closest(name, level) + Server::window_find_closest(name, level) Find window that matches best to given arguments. `name' can be either window name or name of one of the window items. Window window_find_item(name) + Server::window_find_item(name) Find window which contains window item with specified name/server. -Window::item_add(item, automatic) -Window::item_remove(item) -Window::item_destroy(item) - Add/remove/destroy window item +=head2 C + +Add specified windowitem + +=head2 C + +remove specified windowitem + +=head2 C + +destroy specified windowitem + +=head2 C + +Set window active. + +=head2 C + +=head2 C + +=head2 C + +=head2 C + +=head2 C + +Change server/refnum/name/history/level in window. + +=head2 C + +=head2 C -Window::set_active() - Set window active. +Change to previous/next window item. -Window::change_server(server) -Window::set_refnum(refnum) -Window::set_name(name) -Window::set_history(name) -Window::set_level(level) - Change server/refnum/name/history/level in window. -Window::item_prev() -Window::item_next() - Change to previous/next window item. +=head2 C +Return active item's name, or if none is active, window's name -Window::get_active_name() - Return active item's name, or if none is active, window's name +=head2 C -Window::item_find(server, name) - Find window item that matches best to given arguments. +Find window item that matches best to given arguments. diff --git a/docs/Irssi/Windowitem.pod b/docs/Irssi/Windowitem.pod index f91183c..45cde9c 100644 --- a/docs/Irssi/Windowitem.pod +++ b/docs/Irssi/Windowitem.pod @@ -57,3 +57,6 @@ Returns 1 if window item is the active item in parent window. If `item' is a query of a =nick, return DCC chat record of nick. returns L object. + +Windowitem::window_create(automatic) + Create a new window. diff --git a/docs/Signals.pod b/docs/Signals.pod index 4940671..7c1f6db 100644 --- a/docs/Signals.pod +++ b/docs/Signals.pod @@ -251,7 +251,7 @@ B =back -=item C<"send command"> +=item C<"send command"> =over @@ -263,7 +263,7 @@ B =back -=item C<"send text"> +=item C<"send text"> =over @@ -275,9 +275,9 @@ B =back -=item C<"command "> +=item C<"command "> -=over +=over =item string C<$args> @@ -337,7 +337,7 @@ B =over 4 -=item C<"log new"> +=item C<"log new"> =over @@ -413,7 +413,7 @@ B =item C<"module loaded"> -=over +=over =item MODULE_REC C<$module> @@ -423,7 +423,7 @@ B =item C<"module unloaded"> -=over +=over =item MODULE_REC C<$module> @@ -535,7 +535,7 @@ B =over 4 -=item C<"query created"> +=item C<"query created"> =over @@ -545,7 +545,7 @@ B =back -=item C<"query destroyed"> +=item C<"query destroyed"> =over @@ -553,7 +553,7 @@ B =back -=item C<"query nick changed"> +=item C<"query nick changed"> =over -- cgit v1.2.3