diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Formats.pod | 37 | ||||
| -rw-r--r-- | docs/Guide.pod | 5 | ||||
| -rw-r--r-- | docs/Irssi.pod | 186 | ||||
| -rw-r--r-- | docs/Irssi/Channel.pod | 67 | ||||
| -rw-r--r-- | docs/Irssi/Irc/Dcc.pod | 8 | ||||
| -rw-r--r-- | docs/Irssi/Log.pod | 36 | ||||
| -rw-r--r-- | docs/Irssi/Logitem.pod | 4 | ||||
| -rw-r--r-- | docs/Irssi/Nick.pod | 3 | ||||
| -rw-r--r-- | docs/Irssi/Rawlog.pod | 42 | ||||
| -rw-r--r-- | docs/Irssi/UI/Theme.pod | 56 | ||||
| -rw-r--r-- | docs/Signals.pod | 24 |
11 files changed, 316 insertions, 152 deletions
diff --git a/docs/Formats.pod b/docs/Formats.pod new file mode 100644 index 0000000..0902d78 --- /dev/null +++ b/docs/Formats.pod @@ -0,0 +1,37 @@ +__END__ + +=head1 NAME + +Formats + +=head1 DESCRIPTION + +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 % + diff --git a/docs/Guide.pod b/docs/Guide.pod index eba0912..b540e75 100644 --- a/docs/Guide.pod +++ b/docs/Guide.pod @@ -87,7 +87,8 @@ The C<use vars qw($VERSION %IRSSI)> defines two global variables, which are then set below to the appropriate values. C<use Irssi> tells the script to make the various L<Irssi> support functions available. - +Additional parameters passed here with C<qw/.../> can be used to import functions into +the current script namespace. =head1 COMMONLY SCRIPTED TASKS @@ -197,6 +198,8 @@ B<TODO: different types of settings> B<TODO: register/set/get> +B<TODO: Listening for changes and acting accordingly> + =head3 Use Subcommands to Group Script Functionality A common theme in Irssi scripts is to define commands with a prefix, such as diff --git a/docs/Irssi.pod b/docs/Irssi.pod index d67b9aa..c02f852 100644 --- a/docs/Irssi.pod +++ b/docs/Irssi.pod @@ -18,8 +18,8 @@ support is available. If not, refer to the F<INSTALL> file for how to recompile irssi. The C<Irssi> package is the basis of Perl scripting in Irssi. It does not export any -functions, and requires that all function-calls be fully qualified with the -C<Irssi::I<cmd>> prefix. +functions by default, and requires that all function-calls be fully qualified with the +C<Irssi::I<cmd>> prefix. See L</EXPORTS> for alternatives. =head1 CLASSES @@ -31,19 +31,19 @@ B<TODO: fix this list with proper package names> =over 4 -=item L<Irssi::Ban> - =item L<Irssi::Chatnet> -=item L<Irssi::Chatnet> +=item L<Irssi::Command> -=item L<Irssi::Client> +=item L<Irssi::Ignore> -=item L<Irssi::Command> +=item L<Irssi::Irc::Ban> -=item L<Irssi::Dcc> +=item L<Irssi::Irc::Client> -=item L<Irssi::Ignore> +=item L<Irssi::Irc::Dcc> + +=item L<Irssi::Irc::Notifylist> =item L<Irssi::Log> @@ -51,8 +51,6 @@ B<TODO: fix this list with proper package names> =item L<Irssi::Nick> -=item L<Irssi::Notifylist> - =item L<Irssi::Process> =item L<Irssi::Query> @@ -462,104 +460,124 @@ B<TODO: What is this for?> =head3 Modifying Settings +=head4 C<settings_set_str $key, $value> + +=head4 C<settings_set_int $key, $value> + +=head4 C<settings_set_bool $key, $value> + +=head4 C<settings_set_time $key, $value> + +=head4 C<settings_set_level $key, $value> + +=head4 C<settings_set_size $key, $value> + +Changes the value of the setting with key C<$key> to C<$value>. + B<If you change the settings of another module/script with one of these, you must emit a C<"setup changed"> signal afterwards.> -=head4 C<settings_set_str(key, value)> +This can be done with: -=head4 C<settings_set_int(key, value)> + Irssi::signal_emit("setup changed"); -=head4 C<settings_set_bool(key, value)> +=head4 C<settings_remove $key> -=head4 C<settings_set_time(key, value)> +Remove a setting specified with C<$key>. -=head4 C<settings_set_level(key, value)> -=head4 C<settings_set_size(key, value)> +=head2 IO and Process Management -=head4 C<settings_remove(key)> +=head3 C<timeout_add $msecs, $func, $data> -Remove a setting. + 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> -=head2 IO and Process Management +Call `func' once after `msecs' milliseconds (1000 = 1 second) +with parameter `data'. Returns tag which can be used to stop the timeout. + +=head3 C<timeout_remove $tag> + +Remove timeout specified with tag C<$tag>. -timeout_add(msecs, func, data) - Call `func' every `msecs' milliseconds (1000 = 1 second) with - parameter `data'. Returns tag which can be used to stop the timeout. +=head3 C<input_add $source, $condition, $func, $data> -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 `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. -timeout_remove(tag) - Remove timeout with tag. +=head3 C<input_remove $tag> -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. +Remove listener with tag. -input_remove(tag) - Remove listener with tag. +=head3 C<pidwait_add $pid> -pidwait_add(pid) - Adds `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. +Adds `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. -pidwait_remove(pid) - Removes `pid' from the list of processes to wait for. Terminated - processes are removed automatically, so it is usually not necessary - to call this function. +=head3 C<pidwait_remove $pid> +Removes `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 -level2bits(level) +=head3 C<level2bits $level> + Level string -> number -bits2level(bits) +=head3 C<bits2level $bits> + Level number -> string -combine_level(level, str) +=head3 C<combine_level $level, $str> + Combine level number to level string ("+level -level"). Return new level number. =head2 Themes -See also L<Irssi::Theme> +See also L<Irssi::UI::Theme> You can have user configurable texts in scripts that work just like irssi's internal texts that can be changed in themes. First you'll have to register the formats: - -Irssi::theme_register([ - 'format_name', '{hilight my perl format!}', - 'format2', 'testing.. nick = $0, channel = $1' -]); + Irssi::theme_register([ + 'format_name', '{hilight my perl format!}', + 'format2', 'testing.. nick = $0, channel = $1' + ]); Printing happens with one of the functions: -printformat(level, format, ...) -Window::printformat(level, format, ...) -Server::printformat(target, level, format, ...) -Windowitem::printformat(level, format, ...) + printformat $level, $format, ... + + Window::printformat $level, $format, ... + + Server::printformat $target, $level, $format, ... + + Windowitem::printformat $level, $format, ... For example: - $channel->printformat(MSGLEVEL_CRAP, 'format2', - 'nick', $channel->{name}); + $channel->printformat(MSGLEVEL_CRAP, 'format2', + 'nick', $channel->{name}); =head2 DCC +B<TODO: This should probably move to L<Irssi::Irc> + See also L<Irssi::Dcc> Dcc @@ -573,48 +591,58 @@ dcc_find_by_port(nick, port) =head2 Channels -Channel -channel_find(channel) - Find channel from any server. +=head3 C<channel_find $channel> + +Find channel from any server. Returns an L<Irssi::Channel> object. + =head2 Ignores +=head3 C<ignore_add_rec $ignore> -ignore_add_rec(ignore) - Add ignore record. +Add ignore record. + +=head3 C<ignore_update_rec $ignore> + +Update ignore record in configuration + +=head3 C<ignore_check $nick, $host, $channel, $text, $level> + +B<TODO: Document what this does> -ignore_update_rec(ignore) - Update ignore record in configuration -ignore_check(nick, host, channel, text, level) =head2 Logging +=head3 C<log_create_rec $fname, $level> + +Create log file. Returns L<Irssi::Log> -Log -log_create_rec(fname, level) - Create log file. +=head3 C<log_find $fname> + +Find log with file name. Returns L<Irssi::Log> -Log -log_find(fname) - Find log with file name. =head2 Raw Logging -Rawlog rawlog_create() - Create a new rawlog. +=head3 C<rawlog_create> + +Create a new rawlog. Returns an L<Irssi::Rawlog> object. -rawlog_set_size(lines) - Set the default rawlog size for new rawlogs. +=head3 C<rawlog_set_size $lines> + +Set the default rawlog size for new rawlogs. =head2 Chat-Nets -chatnet_find(name) - Find chat network with name. +=head3 C<chatnet_find $name> + +Find chat network with name. =head2 Status Bars +See also L<Irssi::TextUI::Statusbaritem> B<TODO> =head1 COPYRIGHT diff --git a/docs/Irssi/Channel.pod b/docs/Irssi/Channel.pod index bb6789d..baeff6c 100644 --- a/docs/Irssi/Channel.pod +++ b/docs/Irssi/Channel.pod @@ -6,7 +6,8 @@ Irssi::Channel =head1 FIELDS -Channel->{} +C<Channel-E<gt>{}> + type - "CHANNEL" text chat_type - String ID of chat protocol, for example "IRC" @@ -35,45 +36,51 @@ Channel->{} -Server::channels_join(channels, automatic) - Join to channels in server. `channels' may also contain keys for - channels just like with /JOIN command. `automatic' specifies if this - channel was joined "automatically" or if it was joined because join - was requested by user. If channel join is "automatic", irssi doesn't - jump to the window where the channel was joined. +=head2 C<channels_join(channels, automatic)> + +Join to channels in server. `channels' may also contain keys for +channels just like with /JOIN command. `automatic' specifies if this +channel was joined "automatically" or if it was joined because join +was requested by user. If channel join is "automatic", irssi doesn't +jump to the window where the channel was joined. + +=head2 C<destroy> + +Destroy channel. + +=head2 C<bans> + +Return a list of bans in channel. + +=head2 C<ban_get_mask $nick> + +Get ban mask for `nick'. + +=head2 C<banlist_add $ban, $nick, $time> + +Add a new ban to channel. +=head2 C<banlist_remove $ban> -Channel::destroy() - Destroy channel. +Remove a ban from channel. -Channel::bans() - Return a list of bans in channel. +=head2 C<nick_insert $nick, $op, $voice, $send_massjoin> -Channel::ban_get_mask(nick) - Get ban mask for `nick'. +Add nick to nicklist. Returns a L<Irssi::Nick>. -Channel::banlist_add(ban, nick, time) - Add a new ban to channel. +=head2 C<nick_remove $nick> -Channel::banlist_remove(ban) - Remove a ban from channel. +Remove nick from nicklist. +=head2 C<nick_find $nick> -Nick -Channel::nick_insert(nick, op, voice, send_massjoin) - Add nick to nicklist. +Find nick from nicklist. Returns L<Irssi::Nick>. -Channel::nick_remove(nick) - Remove nick from nicklist. +=head2 C<nick_find_mask $mask> -Nick -Channel::nick_find(nick) - Find nick from nicklist. +Find nick mask from nicklist, wildcards allowed. Returns L<Irssi::Nick>. -Nick -Channel::nick_find_mask(mask) - Find nick mask from nicklist, wildcards allowed. +=head2 C<nicks> -Channel::nicks() - Return a list of all nicks in channel. +Return a list of all nicks in channel. diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod index 5950a92..5ba52b9 100644 --- a/docs/Irssi/Irc/Dcc.pod +++ b/docs/Irssi/Irc/Dcc.pod @@ -6,7 +6,7 @@ Irssi::Irc::Dcc =head1 FIELDS -=head2 C<Dcc->{}> +=head2 C<Dcc-E<gt>{}> type - Type of the DCC: chat, send, get orig_type - Original DCC type that was sent to us - same as type except @@ -29,13 +29,13 @@ Irssi::Irc::Dcc starttime - Unix time stamp when the DCC transfer was started transfd - Bytes transferred -=head2 C<Dcc::Chat->{}> +=head2 C<Dcc::Chat-E<gt>{}> id - Unique identifier - usually same as nick mirc_ctcp - Send CTCPs without the CTCP_MESSAGE prefix connection_lost - Other side closed connection -=head2 C<Dcc::Get->{}> +=head2 C<Dcc::Get-E<gt>{}> (..contains all the same data as core Dcc object..) size - File size @@ -47,7 +47,7 @@ Irssi::Irc::Dcc file - The real file name which we use. file_quoted - 1 if file name was received quoted ("file name") -=head2 C<Dcc::Send->{}> +=head2 C<Dcc::Send-E<gt>{}> (..contains all the same data as core Dcc object..) size - File size diff --git a/docs/Irssi/Log.pod b/docs/Irssi/Log.pod index 673a183..68163a2 100644 --- a/docs/Irssi/Log.pod +++ b/docs/Irssi/Log.pod @@ -6,7 +6,8 @@ Irssi::Log =head1 FIELDS -Log->{} +C<Log-E<gt>{}> + fname - Log file name real_fname - The actual opened log file (after %d.%m.Y etc. are expanded) opened - Log file is open @@ -20,27 +21,30 @@ Log->{} =head1 METHODS +=head2 C<update> + +Add log to list of logs / save changes to config file. + +=head2 C<close> + +Destroy log file. + +=head2 C<start_logging> -Log::update() - Add log to list of logs / save changes to config file. +Open log file and start logging. +=head2 C<stop_logging> -Log::close() - Destroy log file. +Close log file. -Log::start_logging() - Open log file and start logging. +=head2 C<item_add $type, $name, $server> -Log::stop_logging() - Close log file. +Add log item to log. -Log::item_add(type, name, server) - Add log item to log. +=head2 C<item_destroy $item> -Log::item_destroy(item) - Remove log item from log. +Remove log item from log. +=head2 C<item_find $type, $item, $server> -Logitem -Log::item_find(type, item, server) - Find item from log. +Find item from log. Returns L<Irssi::Logitem> diff --git a/docs/Irssi/Logitem.pod b/docs/Irssi/Logitem.pod index 6db0c7b..f30d4b8 100644 --- a/docs/Irssi/Logitem.pod +++ b/docs/Irssi/Logitem.pod @@ -6,11 +6,11 @@ Irssi::Logitem =head1 FIELDS -Logitem->{} +C<Logitem-E<gt>{}> + type - 0=target, 1=window refnum name - Name servertag - Server tag - =head1 METHODS diff --git a/docs/Irssi/Nick.pod b/docs/Irssi/Nick.pod index b20d43a..3e85256 100644 --- a/docs/Irssi/Nick.pod +++ b/docs/Irssi/Nick.pod @@ -6,7 +6,8 @@ Irssi::Nick =head1 FIELDS -Nick->{} +C<Nick-E<gt>{}> + type - "NICK" text chat_type - String ID of chat protocol, for example "IRC" diff --git a/docs/Irssi/Rawlog.pod b/docs/Irssi/Rawlog.pod index 7f89c64..a5428bf 100644 --- a/docs/Irssi/Rawlog.pod +++ b/docs/Irssi/Rawlog.pod @@ -7,34 +7,42 @@ Irssi::Rawlog =head1 FIELDS -Rawlog->{} +C<Rawlog-E<gt>{}> + logging - The rawlog is being written to file currently nlines - Number of lines in rawlog =head1 METHODS +=head2 C<destroy> + +Destroy the rawlog. + +=head2 C<get_lines> + +Returns all lines in rawlog. + +=head2 C<open $filename> + +Start logging new messages in rawlog to specified file. + +=head2 C<close> + +Stop logging to file. -Rawlog::destroy() - Destroy the rawlog. +=head2 C<save $filename> -Rawlog::get_lines() - Returns all lines in rawlog. +Save the current rawlog history to specified file. -Rawlog::open(filename) - Start logging new messages in rawlog to specified file. +=head2 C<input $str> -Rawlog::close() - Stop logging to file. +Send `str' to raw log as input text. -Rawlog::save(filename) - Save the current rawlog history to specified file. +=head2 C<output $str> -Rawlog::input(str) - Send `str' to raw log as input text. +Send `str' to raw log as output text. -Rawlog::output(str) - Send `str' to raw log as output text. +=head2 C<redirect $str> -Rawlog::redirect(str) - Send `str' to raw log as redirection text. +Send `str' to raw log as redirection text. diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod index 56e3a3f..4fff169 100644 --- a/docs/Irssi/UI/Theme.pod +++ b/docs/Irssi/UI/Theme.pod @@ -1,3 +1,5 @@ +__END__ + =head1 NAME Irssi::UI::Theme @@ -6,3 +8,57 @@ Irssi::UI::Theme =head1 METHODS +=head1 THEME DOCUMENTATION + +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 :) + +=head2 TEMPLATES + +The real text formats that irssi uses are the ones you can find with +/FORMAT command. Back in the old days all the colors and texts were mixed +up in those formats, and it was really hard to change the colors since you +might have had to change them in tens of different places. So, then came +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. + +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 +below and sets C<parameter1> into C<$0> and C<parameter2> into C<$1> (you can +have more parameters of course). Templates can have subtemplates. Here's a +small example: + + /FORMAT format hello {colorify {underline world}} + + abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; } + +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). + +=head2 COLORS + +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. diff --git a/docs/Signals.pod b/docs/Signals.pod index 7c1f6db..2fcf913 100644 --- a/docs/Signals.pod +++ b/docs/Signals.pod @@ -1606,10 +1606,18 @@ B<Requires to work properly:> =back +=item C<"gui print text finished"> + +=over + +=item L<Irssi::Window> C<$window> + =back (Can be used to determine when all "gui print text"s are sent (not required)) - "gui print text finished", WINDOW_REC + +=back + B<Provides signals:> @@ -1619,7 +1627,19 @@ B<Provides signals:> =item C<"complete word"> -, GList * of char*, WINDOW_REC, char *word, char *linestart, int *want_space +=over + +=item arrayref of string C<$WHAT> B<TODO: ???> + +=item L<Irssi::Window> C<$window> + +=item string C<$word> + +=item string C<$linestart> + +=item int C<$want_space> + +=back =back |