started marking up signals for auto-generation

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;
+#     }
+