POE::Component::IRC::CUsernContributed Perl DocPOE::Component::IRC::Common(3p)



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 parameter, 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 parameter, 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"
       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";
        }

   "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



perl v5.12.2                      2010-11-05   POE::Component::IRC::Common(3p)
