NAME

Sirc::Chantrack - Track information about the channels you're on

SYNOPSIS

    $Channel{$chan}             # true if you're on $channel

    # These only work for channels you are on:
    $Chan_limit{$chan}          # channel limit, or non-existent
    $Chan_user{$chan}{$who}     # true if $who is on $channel
    $Chan_op{$chan}{$who}       # true if $who is an op on $channel
    $Chan_voice{$chan}{$who}    # true if $who has a voice op on $channel

    # These only work for nicks which are on at least one of
    # the channels you are on:
    $Nick{$nick}                # value is $nick, properly cased
    $User_chan{$nick}{$channel} # true for all the channels you and
                                # $nick are both on

    # Overridden functions in main:
    main::userhost $user, $have, $have_not;
    main::userhost [@user_list], $have, $have_not;

    # Sirc::Util-style hooks:
    +op         gets ($channel, $nick), $who is originator
    -op         ditto
    +voice      gets ($channel, $nick), $who is originator
    -voice      ditto
    limit       gets ($channel, $old_limit, $new_limit), $who is originator

DESCRIPTION

This module tracks various data about the channels you are on, and the nicks who are on them with you. It also overrides main::userhost with an enhanced version, and it provides hooks for when people gain and lose ops.

Nothing is exported by default.

Most of the data is available in a series of hashes. These hashes are tied to a package which downcases the keys.

All of the hashes only track data about the channels you are on.

$Channel{channel}

The keys of this hash are the names of the channels you're on. Values are always 1.

$Chan_user{channel}{nick}

This hash of hashes tracks the users on the channels you're on. The values are always 1.

$User_chan{nick}{channel}

This hash of hashes contains the same data as %Chan_user, but with the keys stacked in the opposite order.

$Chan_op{channel}{nick}

This hash of hashes only contains elements for the operators of the given channels. The values are always 1.

$Chan_voice{channel}{nick}

This hash of hashes only contains elements for the people on the channel who have voices. Due to the way /NAMES works, though, it can lack people who were +o when you showed up and got +v before you showed up (even if they subsequenty lose the +o). (It syncs from /names and /mode.) Note that ops can speak without voices. The values are always 1.

$Nick{nick}

This hash maps from any case of nick to the proper case.

main::userhost nick-or-array-ref, have-code [, havenot-code]

This is an overridden version of main::userhost. It uses the cached data to avoid going to the server for information. Additionally, the first arg can be a reference to an array of nicks to check on. If you query multiple users this way they're sent to the server in lots of 5. Lastly, the two code arguments can be either strings or code refs. The data will be in $::who, $::user and $::host when the code runs.

Eg, here's how to run a command which uses userhost info for every user on a channel:

    userhost [keys %{ $Chan_user{$c} }], sub {
        autoop_try $c, "$who!$user\@$host";
    };

+op, -op, +voice, and -voice hooks

These are Sirc::Util-style hooks which are called when people gain and lose ops and voices. They are only called for people who are still in the channel after the gain/loss. That is, an operator leaving the channel does not trigger the -op hook.

The hooks are called with the channel as the first arg and the nick as the second. The originator is in $::who. Eg, here's a trigger which activates when you are given ops:

    use Sirc::Util qw(add_hook ieq);

    add_hook '+op', sub {
        my ($c, $n) = @_;
        timer 10, qq{ main::cmd_autoop "\Q$c\E" }
            if ieq $n, $::nick;
    };

limit hook

This is a Sirc::Util-style hook for channel limit changes. It gets as args the channel name, the old limit, and the new limit. $::who contains the originator.

AVAILABILITY

Check CPAN or http://www.argon.org/~roderick/ for the latest version.

AUTHOR

Roderick Schertler <roderick@argon.org>

SEE ALSO

sirc(1), perl(1), Sirc::Util(3pm).