diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Formats.pod | 162 | ||||
| -rw-r--r-- | docs/Guide.pod | 65 | ||||
| -rw-r--r-- | docs/Irssi.pod | 111 | ||||
| -rw-r--r-- | docs/Irssi/UI/Theme.pod | 33 | ||||
| -rwxr-xr-x | docs/parse_xsfuncs.pl | 55 |
5 files changed, 356 insertions, 70 deletions
diff --git a/docs/Formats.pod b/docs/Formats.pod index 0902d78..0aaca37 100644 --- a/docs/Formats.pod +++ b/docs/Formats.pod @@ -6,32 +6,142 @@ Formats =head1 DESCRIPTION +I<Stuff> + +=head1 COLOURS + Irssi's colors that you can use in text formats, hilights, etc: - text text background - --------------------------------------------------------------------- - %k %K %0 black dark grey black - %r %R %1 red bold red red - %g %G %2 green bold green green - %y %Y %3 yellow bold yellow yellow - %b %B %4 blue bold blue blue - %m %M %5 magenta bold magenta magenta - %p %P magenta (think: purple) - %c %C %6 cyan bold cyan cyan - %w %W %7 white bold white white - %n %N Changes the color to "default color", removing - all other coloring and formatting. %N is always - the terminal's default color. %n is usually too, - except in themes it changes to "previous color", - ie. hello = "%Rhello%n" and "%G{hello} world" - would print hello in red, and %n would turn back - into %G making world green. - %F Blinking on/off (think: flash) - %U Underline on/off - %8 Reverse on/off - %9 %_ Bold on/off - %: Insert newline - %| Marks the indentation position - %# Monospace font on/off (useful with lists and GUI) - %% A single % + C1 C2 C3 Text Colour (C1) Text Colour (C2) Background (C3) + -------------------------------------------------------------------------- + %k %K %0 black dark grey black + %r %R %1 red bold red red + %g %G %2 green bold green green + %y %Y %3 yellow bold yellow yellow + %b %B %4 blue bold blue blue + %m %M %5 magenta bold magenta magenta + %p %P magenta (think: purple) + %c %C %6 cyan bold cyan cyan + %w %W %7 white bold white white + + %n %N Changes the color to "default color", removing + all other coloring and formatting. %N is always + the terminal's default color. %n is usually too, + except in themes it changes to "previous color", + ie. hello = "%Rhello%n" and "%G{hello} world" + would print hello in red, and %n would turn back + into %G making world green. + + %F Blinking on/off (think: flash) + %U Underline on/off + %8 Reverse on/off + %9 %_ Bold on/off + %: Insert newline + %| Marks the indentation position + %# Monospace font on/off (useful with lists and GUI) + %% A single % + + +=head1 VARIABLE SYNTAX + +Irssi supports a number of reserved, dynamic variables, sometimes +referred to as I<expandos>. They are special in that the client is +constantly updating their values automatically. There are also +numerous variable modifiers available. + + Modifier Description + ------------------------------------------------------------------------ + $variable A normal variable, expanding to the first match of: + | 1) an internal SET variable + | 2) an environment variable + $[num]variable Expands to the variables value, with 'num' width. If + | the number is negative, the value is right-aligned. + | The value is padded to meet the width with the + | character given after number (default is space). + | The value is truncated to specified width unless + | '!' character precedes the number. If '.' character + | precedes the number the value isn't padded, just + | truncated. + $#variable Expands to the number of words in $variable. If $variable + | is omitted, it assumes $* + $@variable Expands to the number of characters in $variable. if + | $variable is omitted, it assumes $* + $($subvariable) This is somewhat similar to a pointer, in that the + | value of $subvar is taken as the name of the + | variable to expand to. Nesting is allowed. + ${expression} Permits the value to be embedded in another string + | unambiguously. + $!history! Expands to a matching entry in the client's command + | history, wildcards allowed. + +B<TODO: provide some examples of the various forms of truncation/padding, etc> + +=head1 ALIAS AND FORMAT TEMPLATE ARGUMENTS + +Whenever an alias is called, these expandos are set to the arguments passed +to it. If none of these expandos are used in the alias, or the C<$()> form +shown above, any arguments passed will automatically be appended to the last +command in the alias. + + Expando Description + ------------------------------------------------------------------------ + $* expands to all arguments passed to an alias + $n expands to argument 'n' passed to an alias (counting from zero) + $n-m expands to arguments 'n' through 'm' passed to an alias + $n- expands to all arguments from 'n' on passed to an alias + $-m expands to all arguments up to 'm' passed to an alias + $~ expands to the last argument passed to an alias + +=head1 EXPANDOS (SPECIAL VARIABLES) + +These variables are set and updated dynamically by the client. The case of +C<$A .. $Z> is important. + + Variable Description + ------------------------------------------------------------------------ + $, last person who sent you a MSG + $. last person to whom you sent a MSG + $: last person to join a channel you are on + $; last person to send a public message to a channel you are on + $A text of your AWAY message, if any + $B body of last MSG you sent + $C current channel + $D last person that NOTIFY detected a signon for + $E idle time + $F time client was started, $time() format + $H current server numeric being processed + $I channel you were last INVITEd to + $J client version text string + $K current value of CMDCHARS + $k first character in CMDCHARS + $L current contents of the input line + $M modes of current channel, if any + $N current nickname + $O value of STATUS_OPER if you are an irc operator + $P if you are a channel operator in $C, expands to a '@' + $Q nickname of whomever you are QUERYing + $R version of current server + $S current server name + $T target of current input (channel or nick of query) + $U value of cutbuffer + $V client release date (format YYYYMMDD) + $W current working directory + $X your /userhost $N address (user@host) + $Y value of REALNAME + $Z time of day (hh:mm, can be changed with /SET timestamp_format) + $$ a literal '$' + $versiontime prints time of the irssi version in HHMM format + $sysname system name (eg. Linux) + $sysrelease system release (eg. 2.2.18) + $sysarch system architecture (eg. i686) + $topic channel topic + $usermode user mode + $cumode own channel user mode + $cumode_space like $cumode, but gives space if there's no mode. + $tag server tag + $chatnet chat network of server + $winref window reference number + $winname window name + $itemname like $T, but use item's visible_name which may be + different (eg. $T = !12345chan, $itemname = !chan) diff --git a/docs/Guide.pod b/docs/Guide.pod index b540e75..a5a20f2 100644 --- a/docs/Guide.pod +++ b/docs/Guide.pod @@ -21,7 +21,15 @@ better, create a symlink to it) into F<~/.irssi/scripts/autorun/>. =head2 Testing -B<TODO: Forgotten what was going to go here> +=for comment B<TODO: Forgotten what was going to go here> + +=head3 C</SCRIPT EXEC> + +B<TODO: Using it for testing stuff out> + +B<TODO: Also for very short scripts (with -permanent?)> + +B<TODO: Quoting rules for vars and things?> =head2 Loading @@ -142,7 +150,33 @@ B<TODO: Example here> =head3 Using Functions -B<TODO: Find the example code that demonstrates this> +Because scripts exist in a well-defined namespace of C<Irssi::Script::SOMEPACKAGE>, +it is possible to manipulate the perl symbol table to call functions directly on them, +assuming they are loaded. + +Because the following code depends on I<symbolic references>, it is necessary to +tell Perl to allow them, despite normally being prohibited by C<use strict>. +The C<no strict 'refs';> line takes care of this, and reenables them at the end +of the snippet. + + no strict 'refs'; + if (defined %{ 'Irssi::Script::SOMEPACKAGE::' }) { + if (defined &{'Irssi::Script::SOMEPACKAGE::SOME_FUNC'} ) { + (&{'Irssi::Script::SOMEPAKAGE::SOME_FUNC'}(@args)); + } else { + print("Err: can't find Irssi::Script::SOMEPACKAGE::SOME_FUNC"); + } + } + use strict 'refs'; + +Here, C<SOMEPACKAGE> is the name of the script package which contains the +function you want to call, and C<SOME_FUNC> is the name of the function within +it you wish to call. The first 2 C<defined(..)> lines take care of ensuring +that the package and function exist, and generate an error otherwise. Other +error handling is possible, including executing a C</SCRIPT LOAD> to load the +necessary script and retry, but is not shown here. + +I<This snippet was provided by C<Bazerka> on Freenode/#irssi.> =head2 If In Doubt, Dump! @@ -170,8 +204,20 @@ 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: example - catch or rebind /HELP, then check args and either print and -sig_stop or continue> + our $help = "this is help for b"; + + Irssi::command_bind('help', sub { + if ($_[0] eq 'test_b') { + Irssi::print($help, MSGLEVEL_CLIENTCRAP); + Irssi::signal_stop; + return; + } + } + ); + +This example demonstrates overriding the C</HELP> command, and if the argument +matches our command, print some custom help and prevent the internal Irssi help +function from being called. Otherwise, it falls back to the default help. =head3 Use Tab Completion @@ -227,6 +273,17 @@ The following example demonstrates how to use subcommands from within a script: print "subcommand called with: $args"; } +=head1 AUTHOR & THANKS + +This page was written by Tom Feist C<shabble+irssi@metavore.org>, but draws +on the help of many many people. + +The denizens of Freenode/#irssi have been particularly helpful, especially +C<Bazerka> and C<nightfrog>. + +To report bugs or suggestions, email me at the address before, or come talk to +me in C<#irssi> on C<irc.freenode.net>. + =head1 OTHER RESOURCES The documentation assembled here and elsewhere on this site has been drawn from diff --git a/docs/Irssi.pod b/docs/Irssi.pod index c02f852..85b36dd 100644 --- a/docs/Irssi.pod +++ b/docs/Irssi.pod @@ -83,6 +83,7 @@ For example: =head1 METHODS + =head2 Accessors =head3 C<active_win> @@ -299,12 +300,14 @@ remainder of the string to be processed as desired. =head4 C<command_runsub $cmd, $data, $server, $item> -Run subcommands for `cmd'. First word in `data' is parsed as -subcommand. `server' is L<Irssi::Server> record for current -L<Irssi::Windowitem> `item'. +Run subcommands for C<$cmd>. First word in C<$data> is parsed as +subcommand. C<$server> is L<Irssi::Server> record for current +L<Irssi::Windowitem> C<$item>. + +Call command_runsub in handler function for C<$cmd> and bind +with: -Call command_runsub in handler function for `cmd' and bind -with command_bind("`cmd' `subcmd'", subcmdfunc[, category]); + command_bind("$cmd $subcmd", subcmdfunc[, category]); See the L<example|Guide/Use Subcommands to Group Script Functionality> for further details. @@ -436,7 +439,8 @@ 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. +An irssi Messagelevel. See C</HELP LEVELS> for a full list and description, or +L</Message Levels> for a description of the Perl equivalents. =item C<size> @@ -490,14 +494,15 @@ Remove a setting specified with C<$key>. =head3 C<timeout_add $msecs, $func, $data> - Call C<$func> every C<$msecs> milliseconds (1/1000th of a second) with - parameter C<$data>. Returns a tag which can be used to stop the timeout via - L</timeout_remove $tag>. +Call C<$func> every C<$msecs> milliseconds (1/1000th of a second) with +parameter C<$data>. Returns a tag which can be used to stop the timeout via +L</timeout_remove $tag>. =head3 C<timeout_add_once $msecs, $func, $data> -Call `func' once after `msecs' milliseconds (1000 = 1 second) -with parameter `data'. Returns tag which can be used to stop the timeout. +Call C<$func> once after C<$msecs> milliseconds (1000 = 1 second) with parameter +C<$data>. Returns tag which can be used to stop the timeout via +L</timeout_remove $tag>. =head3 C<timeout_remove $tag> @@ -505,43 +510,104 @@ Remove timeout specified with tag C<$tag>. =head3 C<input_add $source, $condition, $func, $data> -Call `func' with parameter `data' when specified IO happens. -`source' is the file handle that is being listened. `condition' can -be INPUT_READ, INPUT_WRITE or both. Returns tag which can be used to -remove the listener. +Call C<$func> with parameter C<$data> when specified IO happens. C<$source> is +the file handle that is being listened. C<$condition> can be +C<Irssi::INPUT_READ>, C<Irssi::INPUT_WRITE> or both. Returns tag which can be +used to remove the listener with L</input_remove $tag>. =head3 C<input_remove $tag> -Remove listener with tag. +Remove listener with C<$tag>. =head3 C<pidwait_add $pid> -Adds `pid' to the list of processes to wait for. The pid must identify +Adds C<$pid> to the list of processes to wait for. The pid must identify a child process of the irssi process. When the process terminates, a "pidwait" signal will be sent with the pid and the status from waitpid(). This is useful to avoid zombies if your script forks. =head3 C<pidwait_remove $pid> -Removes `pid' from the list of processes to wait for. Terminated +Removes C<$pid> from the list of processes to wait for. Terminated processes are removed automatically, so it is usually not necessary to call this function. =head2 Message Levels +The standard Irssi levels (as specified in C</HELP LEVELS>) are accessible from +within scripts with the following zero-arguments functions: + +=over + +=item C<MSGLEVEL_CRAP> + +=item C<MSGLEVEL_MSGS> + +=item C<MSGLEVEL_PUBLIC> + +=item C<MSGLEVEL_NOTICES> + +=item C<MSGLEVEL_SNOTES> + +=item C<MSGLEVEL_CTCPS> + +=item C<MSGLEVEL_ACTIONS> + +=item C<MSGLEVEL_JOINS> + +=item C<MSGLEVEL_PARTS> + +=item C<MSGLEVEL_QUITS> + +=item C<MSGLEVEL_KICKS> + +=item C<MSGLEVEL_MODES> + +=item C<MSGLEVEL_TOPICS> + +=item C<MSGLEVEL_WALLOPS> + +=item C<MSGLEVEL_INVITES> + +=item C<MSGLEVEL_NICKS> + +=item C<MSGLEVEL_DCC> + +=item C<MSGLEVEL_DCCMSGS> + +=item C<MSGLEVEL_CLIENTNOTICE> + +=item C<MSGLEVEL_CLIENTCRAP> + +=item C<MSGLEVEL_CLIENTERROR> + +=item C<MSGLEVEL_HILIGHT> + +=item C<MSGLEVEL_ALL> + +=item C<MSGLEVEL_NOHILIGHT> + +=item C<MSGLEVEL_NO_ACT> + +=item C<MSGLEVEL_NEVER> + +=item C<MSGLEVEL_LASTLOG> + +=back + =head3 C<level2bits $level> - Level string -> number +Level string -> number =head3 C<bits2level $bits> - Level number -> string +Level number -> string =head3 C<combine_level $level, $str> - Combine level number to level string ("+level -level"). - Return new level number. +Combine level number to level string (C<"+level -level">). +Return new level number. =head2 Themes @@ -611,7 +677,6 @@ Update ignore record in configuration B<TODO: Document what this does> - =head2 Logging =head3 C<log_create_rec $fname, $level> diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod index 4fff169..2e69186 100644 --- a/docs/Irssi/UI/Theme.pod +++ b/docs/Irssi/UI/Theme.pod @@ -13,7 +13,7 @@ Irssi::UI::Theme When testing changes, the easiest way to reload the theme is with /RELOAD. This reloads the configuration file too, so if you did any changes remember to /SAVE it first. Remember also that /SAVE overwrites the theme file with -old data so keep backups :) +old data so keep backups C<:)> =head2 TEMPLATES @@ -26,9 +26,9 @@ this templating system. Now the C</FORMAT>s don't have any colors in them, and they also have very little other styling. Most of the stuff you need to change is in this theme file. If you can't change something here, you can always go back -to change the /FORMATs directly, they're also saved in these .theme files. +to change the /FORMATs directly, they're also saved in the F<*.theme> files. -So .. the templates. They're those C<{blahblah}> parts you see all over the +So, the templates. They're those C<{blahblah}> parts you see all over the /FORMATs and here. Their usage is simply C<{name parameter1 parameter2}>. When irssi sees this kind of text, it goes to find "name" from abstracts block @@ -44,21 +44,20 @@ When irssi expands the templates in "format", the final string would be: hello %G%Uworld%U%n -ie. underlined bright green "world" text. -and why C<$0->, why not C<$0>? C<$0> would only mean the first parameter, -$0- means all the parameters. With {underline hello world} you'd really -want to underline both of the words, not just the hello (and world would -actually be removed entirely). +ie. underlined bright green "world" text. and why C<$0->, why not C<$0>? C<$0> +would only mean the first parameter, $0- means all the parameters. With +{underline hello world} you'd really want to underline both of the words, not +just the hello (and world would actually be removed entirely). -=head2 COLORS +=head2 COLOURS You can find definitions for the color format codes in L<Formats> -There's one difference here though. %n format. Normally it means the -default color of the terminal (white mostly), but here it means the -"reset color back to the one it was in higher template". For example -if there was /FORMAT test %g{foo}bar, and foo = "%Y$0%n", irssi would -print yellow "foo" (as set with %Y) but "bar" would be green, which was -set at the beginning before the {foo} template. If there wasn't the %g -at start, the normal behaviour of %n would occur. If you _really_ want -to use the terminal's default color, use %N. +There's one difference here though. C<%n> format. Normally it means the default +color of the terminal (white mostly), but here it means the "reset color back to +the one it was in higher template". For example if there was C</FORMAT test +%g{foo}bar>, and C<foo = "%Y$0%n">, irssi would print yellow C<"foo"> (as set +with C<%Y>) but C<"bar"> would be green, which was set at the beginning before +the C<{foo}> template. If there wasn't the C<%g> at start, the normal behaviour +of C<%n> would occur. If you I<really> want to use the terminal's default color, +use C<%N>. diff --git a/docs/parse_xsfuncs.pl b/docs/parse_xsfuncs.pl new file mode 100755 index 0000000..4ce196f --- /dev/null +++ b/docs/parse_xsfuncs.pl @@ -0,0 +1,55 @@ +#!/usr/bin/env perl + +use strict; +use warnings; + +use Glib::ParseXSDoc; +use File::Find; +use Data::Dumper; + +my $home = $ENV{HOME}; +my $src_dir = "$home/sources/irssi/src/perl"; +$ENV{FORCE_DATA_DUMPER} = 1; +print "=over\n\n"; + +find(\&process_file, $src_dir); + +print "=back\n\n"; + +sub process_file { + my $filename = $_; + return unless $filename =~ /\.xs$/; + + my $filepath = $File::Find::name; +# print "Processing file: $filepath\n"; + + my $parser = Glib::ParseXSDoc->new; #xsdocparse($filepath); + + $parser->parse_file($filepath); + $parser->canonicalize_xsubs; + $parser->swizzle_pods; + $parser->preprocess_pods; + $parser->clean_out_empty_pods; + + #print Dumper($parser->{data}), $/; + my $data = $parser->{data}; + foreach my $package (keys %$data) { + #print "Package: $package\n"; + my $subs = $data->{$package}->{xsubs}; + foreach my $sub (@$subs) { + my $sub_name = $sub->{symname}; + next if $sub_name =~ m/::$/; + print_msglevel($sub_name); + #print $sub->{symname}, $/; + } + } +} + +sub print_msglevel { + my ($sym) = @_; + if ($sym =~ m/::MSGLEVEL/) { + $sym =~ s/^Irssi:://; + print "=item C<$sym>\n\n"; + } +} + |