aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTom Feist <shabble@cowu.be>2010-07-12 20:13:36 +0000
committerTom Feist <shabble@cowu.be>2010-07-12 20:13:36 +0000
commitb0ae07d0e1a750afabce530d23288212ca1fd5b6 (patch)
treec0905e3ac6b4cb2dbe5fb4caaa2abb10bca8f666
parentmore reformattingm, added a guide.pm for general stuff (diff)
downloadirssi-scripts-b0ae07d0e1a750afabce530d23288212ca1fd5b6.tar.gz
irssi-scripts-b0ae07d0e1a750afabce530d23288212ca1fd5b6.zip
started marking up signals for auto-generation
Diffstat (limited to '')
-rw-r--r--docs/Guide.pm16
-rw-r--r--docs/Irssi.pm58
-rw-r--r--docs/Signals.pm105
-rwxr-xr-xdocs/buildsignals.pl56
4 files changed, 216 insertions, 19 deletions
diff --git a/docs/Guide.pm b/docs/Guide.pm
index 78aae10..2f71e1c 100644
--- a/docs/Guide.pm
+++ b/docs/Guide.pm
@@ -37,18 +37,21 @@ network connections or processes, and restore any Irssi modifications made.
=head1 ANATOMY OF A SCRIPT
-In this section, we develop a very simplistic script
+In this section, we develop a very simplistic script and look at the
+necessary code.
=head2 Preamble
=head1 USEFUL THINGS
-=head2 Sharing code between scripts
-
+=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
+
+=head3 Using Functions
=head2 If In Doubt, Dump!
@@ -63,6 +66,13 @@ 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 Script Look Native
+
+=head3 Provide Help
+
+=head3 Use Tab Completion
+
+=head3 Use Settings for Customisation
=head1 OTHER RESOURCES
diff --git a/docs/Irssi.pm b/docs/Irssi.pm
index a741b2e..2c93256 100644
--- a/docs/Irssi.pm
+++ b/docs/Irssi.pm
@@ -266,7 +266,7 @@ See also L<Irssi::Command>
=head3 Registering Commands
-=head4 C<command_bind $cmd, $func, $category
+=head4 C<command_bind $cmd, $func, $category>
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
@@ -299,29 +299,59 @@ See also L<Irssi::Server/command $string>
=head3 Parsing Command Arguments
-=head4 C<command_set_options(cmd, data)>
+=head4 C<command_set_options $cmd, $data>
-Set options for command `cmd' to `data'. `data' is a string of
+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
+=over 16
-=item '-': optional argument
+=item C<->: optional argument
-=item '+': argument required
+=item C<@>: optional numeric argument
-=item '@': optional numeric argument
+=item C<+>: required argument
=back
-=head4 C<command_parse_options(cmd, data)>
+For example:
+
+ my $argument_format = "+something -other -another @number";
+ Irssi::command_set_options('mycmd', $argument_format);
+
+Thus, the command may be run as C</mycmd -something value -other value rest of args>.
+
+=head4 C<command_parse_options $cmd, $data>
+
+Parse out options as specified by L<command_set_options|/command_set_options
+$cmd, $data> 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<undef> 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.
-Parse options for command `cmd' in `data'. It returns a reference to
-an hash table with the options and a string with the remaining part
-of `data'. On error it returns the undefined value.
+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
@@ -510,10 +540,14 @@ rawlog_set_size(lines)
chatnet_find(name)
Find chat network with name.
+=head2 Status Bars
+
+B<TODO>
=head1 COPYRIGHT
-All the content of this site is copyright © 2000-2010 The Irssi project.
+All the content of this site is copyright E<copy> 2000-2010 L<The Irssi
+project|http://irssi.org>.
Formatting to POD and linking by Tom Feist
L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org>
diff --git a/docs/Signals.pm b/docs/Signals.pm
index d6d3ec9..1fadc32 100644
--- a/docs/Signals.pm
+++ b/docs/Signals.pm
@@ -13,6 +13,88 @@ Irssi.
See L<Irssi/"Signals">
+=begin irssi_signal_types
+
+=head SIGNAL ARGUMENT TYPES
+
+=over
+
+=item C<GList * of ([^,]*)> C<glistptr_$1>
+
+=item C<GSList * of (\w+)s> C<gslist_$1>
+
+=item C<char *> C<string>
+
+=item C<ulong *> C<ulongptr>
+
+=item C<int *> C<intptr>
+
+=item C<int> C<int>
+
+
+
+=item C<CHATNET_REC> C<iobject>
+
+=item C<SERVER_REC> C<iobject>
+
+=item C<RECONNECT_REC> C<iobject>
+
+=item C<CHANNEL_REC> C<iobject>
+
+=item C<QUERY_REC> C<iobject>
+
+=item C<COMMAND_REC> C<iobject>
+
+=item C<NICK_REC> C<iobject>
+
+=item C<LOG_REC> C<Irssi::Log>
+
+=item C<RAWLOG_REC> C<Irssi::Rawlog>
+
+=item C<IGNORE_REC> C<Irssi::Ignore>
+
+=item C<MODULE_REC> C<Irssi::Module>
+
+
+=item C<BAN_REC> C<Irssi::Irc::Ban>
+
+=item C<NETSPLIT_REC> C<Irssi::Irc::Netsplit>
+
+=item C<NETSPLIT_SERVER__REC> C<Irssi::Irc::Netsplitserver>
+
+
+=item C<DCC_REC> C<siobject>
+
+=item C<AUTOIGNORE_REC> C<Irssi::Irc::Autoignore>
+
+=item C<AUTOIGNORE_REC> C<Irssi::Irc::Autoignore>
+
+=item C<NOTIFYLIST_REC> C<Irssi::Irc::Notifylist>
+
+=item C<CLIENT_REC> C<Irssi::Irc::Client>
+
+
+=item C<THEME_REC> C<Irssi::UI::Theme>
+
+=item C<KEYINFO_REC> C<Irssi::UI::Keyinfo>
+
+=item C<PROCESS_REC> C<Irssi::UI::Process>
+
+=item C<TEXT_DEST_REC> C<Irssi::UI::TextDest>
+
+=item C<WINDOW_REC> C<Irssi::UI::Window>
+
+=item C<WI_ITEM_REC> C<iobject>
+
+
+
+=item C<PERL_SCRIPT_REC> C<Irssi::Script>
+
+=back
+
+
+=end irssi_signal_types
+
=head1 SIGNAL DEFINITIONS
The following signals are categorised as in the original documentation, but
@@ -20,21 +102,25 @@ have been revised to note Perl variable types and class names.
Arguments are passed to signal handlers in the usual way, via C<@_>.
-
+=for irssi_signal_defs START OF SIGNAL DEFINITIONS
=head2 Core
=over 4
=item C<"gui exit">
+
I<None>
=item C<"gui dialog">
- string C<$type>, string C<$text>
+
+string C<$type>, string C<$text>
=item C<"send command">
- C<string $command> L<Irssi::Server> C<$server>, L<Irssi::Windowitem>
- C<$window_item>
+
+C<string $command>,
+L<Irssi::Server> C<$server>,
+L<Irssi::Windowitem> C<$window_item>
=back
@@ -503,3 +589,14 @@ B<Provides signals:>
=item C<"script error"> PERL_SCRIPT_REC, string C<$errormsg>
=back
+
+=for irssi_signal_defs END OF SIGNAL DEFINITIONS
+
+=head1 SIGNAL AUTO-GENERATION
+
+This file is used to auto-generate the signal definitions used by Irssi, and hence
+must be edited in order to add new signals.
+
+=head2 Format
+
+
diff --git a/docs/buildsignals.pl b/docs/buildsignals.pl
new file mode 100755
index 0000000..11cd74a
--- /dev/null
+++ b/docs/buildsignals.pl
@@ -0,0 +1,56 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+use Data::Dumper;
+
+package Pod::Simple::IrssiSignalParser;
+
+use base qw/Pod::Simple::PullParser/;
+
+use Data::Dumper;
+
+sub run {
+ my $self = shift;
+
+ my ($seen_start, $seen_end) = (0,0);
+ my $text_token;
+
+ Token:
+
+ while(my $token = $self->get_token()) {
+ #print "PRocessing token: $token\n";
+
+ if (!$seen_start && $token->is_start) {
+ if ($token->tag eq 'Data') {
+ print "Start Data token: $token\n";
+
+ $text_token = $self->get_token;
+
+ if ($text_token->is_text && $text_token->text =~ /START/) {
+ print "Found start!\n\n";
+ $seen_start = 1;
+ }
+ }
+ }
+ }
+}
+
+package main;
+
+my $input_file = $ARGV[0] // 'Signals.pm';
+my $parser = Pod::Simple::IrssiSignalParser->new;
+
+$parser->accept_targets('irssi_signal_defs', 'irssi_signal_types');
+my $tree = $parser->parse_file($input_file);
+
+
+# if ($type eq 'Data' && $text =~ /START OF SIGNAL DEFINITIONS/) {
+# $seen_start = 1;
+# }
+
+# if ($type eq 'Data' && $text =~ /END OF SIGNAL DEFINITIONS/) {
+# $seen_end = 1;
+# }
+