The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POE-Component-IRC-6.18
River stage three • 54 direct dependents • 109 total dependents
12 ++
/ POE::Component::IRC::Common

NAME

POE::Component::IRC::Common - Provides a set of common functions for the POE::Component::IRC suite

SYNOPSIS

 use strict;
 use warnings;

 use POE::Component::IRC::Common qw( :ALL );

 my $nickname = '^Lame|BOT[moo]';
 my $uppercase_nick = u_irc( $nickname );
 my $lowercase_nick = l_irc( $nickname );

 my $mode_line = 'ov+b-i Bob sue stalin*!*@*';
 my $hashref = parse_mode_line( $mode_line );

 my $banmask = 'stalin*';
 my $full_banmask = parse_ban_mask( $banmask );

 if ( matches_mask( $full_banmask, 'stalin!joe@kremlin.ru' ) ) {
     print "EEK!";
 }

 if ( has_color($message) ) {
    print 'COLOR CODE ALERT!";
 }

 my $results_hashref = matches_mask_array( \@masks, \@items_to_match_against );

 my $nick = parse_user( 'stalin!joe@kremlin.ru' );
 my ($nick, $user, $host) = parse_user( 'stalin!joe@kremlin.ru' );

DESCRIPTION

POE::Component::IRC::Common provides a set of common functions for the POE::Component::IRC suite. There are included functions for uppercase and lowercase nicknames/channelnames and for parsing mode lines and ban masks.

CONSTANTS

Use the following constants to add formatting and mIRC color codes to IRC messages.

Normal text:

 NORMAL

Formatting:

 BOLD
 UNDERLINE
 REVERSE
 ITALIC
 FIXED

Colors:

 WHITE
 BLACK
 DARK_BLUE
 DARK_GREEN
 RED
 BROWN
 PURPLE
 ORANGE
 YELLOW
 LIGHT_GREEN
 TEAL
 CYAN
 LIGHT_BLUE
 MAGENTA
 DARK_GREY
 LIGHT_GREY

Individual formatting codes can be cancelled with their corresponding constant, but you can also cancel all of them at once with NORMAL. To cancel the effect of previous color codes, you must use NORMAL. which of course has the side effect of cancelling the effect of all previous formatting codes as well.

 $irc->yield('This word is ' . YELLOW . 'yellow' . NORMAL
     . ' while this word is ' . BOLD . 'bold' . BOLD);

 $irc->yield(UNDERLINE . BOLD . 'This sentence is both underlined and bold.'
     . NORMAL);

FUNCTIONS

u_irc

Takes one mandatory parameter, a string to convert to IRC uppercase, and one optional parameter, the casemapping of the ircd ( which can be 'rfc1459', 'strict-rfc1459' or 'ascii'. Default is 'rfc1459' ). Returns the IRC uppercase equivalent of the passed string.

l_irc

Takes one mandatory parameter, a string to convert to IRC lowercase, and one optional parameter, the casemapping of the ircd ( which can be 'rfc1459', 'strict-rfc1459' or 'ascii'. Default is 'rfc1459' ). Returns the IRC lowercase equivalent of the passed string.

parse_mode_line

Takes a list representing an IRC mode line. Returns a hashref. If the modeline couldn't be parsed the hashref will be empty. On success the following keys will be available in the hashref:

'modes', an arrayref of normalised modes;

'args', an arrayref of applicable arguments to the modes;

Example:

 my $hashref = parse_mode_line( 'ov+b-i', 'Bob', 'sue', 'stalin*!*@*' );

 # $hashref will be:
 {
    modes => [ '+o', '+v', '+b', '-i' ],
    args  => [ 'Bob', 'sue', 'stalin*!*@*' ],
 }

parse_ban_mask

Takes one parameter, a string representing an IRC ban mask. Returns a normalised full banmask.

Example:

 $fullbanmask = parse_ban_mask( 'stalin*' );

 # $fullbanmask will be: 'stalin*!*@*';

matches_mask

Takes two parameters, a string representing an IRC mask ( it'll be processed with parse_ban_mask() to ensure that it is normalised ) and something to match against the IRC mask, such as a nick!user@hostname string. Returns a true value if they match, a false value otherwise. Optionally, one may pass the casemapping (see u_irc), as this function uses u_irc internally.

matches_mask_array

Takes two array references, the first being a list of strings representing IRC masks, the second a list of somethings to test against the masks. Returns an empty hashref if there are no matches. Otherwise, the keys will be the masks matched, each value being an arrayref of the strings that matched it. Optionally, one may pass the casemapping (see u_irc), as this function uses u_irc internally.

parse_user

Takes one parameter, a string representing a user in the form nick!user@hostname. In a scalar context it returns just the nickname. In a list context it returns a list consisting of the nick, user and hostname, respectively.

has_color

Takes one parameter, a string of IRC text. Returns 1 if it contains any IRC color codes, 0 otherwise. Useful if you want your bot to kick users for (ab)using colors. :)

has_formatting

Takes one parameter, a string of IRC text. Returns 1 if it contains any IRC formatting codes, 0 otherwise.

strip_color

Takes one paramter, a string of IRC text. Returns the string stripped of all IRC color codes. Due to the fact that both color and formatting codes can be cancelled with the same character, this might strip more than you hoped for if the string contains both color and formatting codes. Stripping both will always do what you expect it to.

strip_formatting

Takes one paramter, a string of IRC text. Returns the string stripped of all IRC formatting codes. Due to the fact that both color and formatting codes can be cancelled with the same character, this might strip more than you hoped for if the string contains both color and formatting codes. Stripping both will always do what you expect it to.

irc_to_utf8

The IRC messages you get from POE::Component::IRC are raw byte strings that have no inherent encoding. Most popular clients (mIRC, xchat, certain irssi configurations) encode their messages in Microsoft's CP1252 encoding (their version of Latin-1) if the message only contains characters which fit into Latin-1, otherwise falling back to UTF-8 encoding. Writing something like this to a file, terminal, or database is a recipe for disaster.

This function takes a byte string (e.g. a message from an irc_public handler) in "IRC encoding" and returns a text string. Since the source encoding might have been UTF-8, you should encode/store it in UTF-8 or some other Unicode encoding in your file/database/whatever.

 use POE::Component::IRC::Common qw(irc_to_utf8);

 sub irc_public {
     my ($who, $where, $what) = @_[ARG0..ARG2];

     # not wise, $what is either CP1252 or UTF-8
     print $what, "\n";

     $what = irc_to_utf8($what);

     # good, $what is always UTF-8
     print $what, "\n";
 }

See also Encode, perluniintro, perlunitut, perlunicode, and perlunifaq.

irc_ip_get_version

Try to guess the IP version of an IP address.

Params: IP address Returns: 4, 6, 0(unable to determine)

$version = ip_get_version ($ip)

irc_ip_is_ipv4

Check if an IP address is of type 4.

Params: IP address Returns: 1 (yes) or 0 (no)

ip_is_ipv4($ip) and print "$ip is IPv4";

irc_ip_is_ipv6

Check if an IP address is of type 6.

Params: IP address Returns: 1 (yes) or 0 (no)

 ip_is_ipv6($ip) && print "$ip is IPv6";

AUTHOR

Chris 'BinGOs' Williams

IP functions are shamelessly 'borrowed' from Net::IP by Manuel Valente

SEE ALSO

POE::Component::IRC

Net::IP