From b0ae07d0e1a750afabce530d23288212ca1fd5b6 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 12 Jul 2010 21:13:36 +0100 Subject: started marking up signals for auto-generation --- docs/Guide.pm | 16 ++++++-- docs/Irssi.pm | 58 ++++++++++++++++++++++------ docs/Signals.pm | 105 +++++++++++++++++++++++++++++++++++++++++++++++++-- docs/buildsignals.pl | 56 +++++++++++++++++++++++++++ 4 files changed, 216 insertions(+), 19 deletions(-) create mode 100755 docs/buildsignals.pl 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): /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 =head3 Registering Commands -=head4 C 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 =head3 Parsing Command Arguments -=head4 C +=head4 C -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 +For example: + + my $argument_format = "+something -other -another @number"; + Irssi::command_set_options('mycmd', $argument_format); + +Thus, the command may be run as C. + +=head4 C + +Parse out options as specified by L 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 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 =head1 COPYRIGHT -All the content of this site is copyright © 2000-2010 The Irssi project. +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/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 +=begin irssi_signal_types + +=head SIGNAL ARGUMENT TYPES + +=over + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + + + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + + +=item C C + +=item C C + +=item C C + + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + +=item C C + + + +=item C C + +=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 =item C<"gui dialog"> - string C<$type>, string C<$text> + +string C<$type>, string C<$text> =item C<"send command"> - C L C<$server>, L - C<$window_item> + +C, +L C<$server>, +L C<$window_item> =back @@ -503,3 +589,14 @@ B =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; +# } + -- cgit v1.2.3