NAME

"Net::Async::IRC" - use IRC with "IO::Async"

SYNOPSIS 

     use IO::Async::Loop;
     use Net::Async::IRC;

     my $loop = IO::Async::Loop->new;

     my $irc = Net::Async::IRC->new(
        on_message_text => sub {
           my ( $self, $message, $hints ) = @_;

           print "$hints->{prefix_name} says: $hints->{text}\n";
        },
     );

     $loop->add( $irc );

     $irc->login(
        nick => "MyName",

        host => "irc.example.org",

        on_login => sub {
           $irc->send_message( "PRIVMSG", undef, "YourName", "Hello world!" );
        },
     );

     $loop->loop_forever;

DESCRIPTION

This object class implements an asynchronous IRC client, for use in programs based on IO::Async.

This documentation is very much still in a state of TODO; it is being released now in the hope it is currently somewhat useful, with the intention of putting more work into both the code and its documentation at some near point in the future.

PARAMETERS

The following named parameters may be passed to "new" or "configure":

nick => STRING
user => STRING
realname => STRING

Connection details. See also "connect", "login". 

            If "user" is not supplied, it will default to either
            $ENV{LOGNAME} or the current user's name as supplied by
            "getpwuid()".

            If unconnected, changing these properties will set the default
            values to use when logging in.

            If logged in, changing the "nick" property is equivalent to
            calling "change_nick". Changing the other properties will not
            take effect until the next login.

METHODS
$irc->connect( %args )
Connects to the IRC server. This method does not perform the complete IRC login sequence; for that see instead the "login" method.

host => STRING

Hostname of the IRC server.

service => STRING or NUMBER 

            Optional. Port number or service name of the IRC server.
            Defaults to 6667.

on_connected => CODE 

            Continuation to invoke once the connection has been established.
            Usually used by the "login" method to perform the actual login
            sequence.

             $on_connected->( $irc )

on_error => CODE 

            Continuation to invoke in the case of an error preventing the
            connection from taking place.

             $on_error->( $errormsg )

Any other arguments are passed into the underlying "IO::Async::Loop" "connect" method.

$irc->login( %args )
Logs in to the IRC network, connecting first using the "connect" method if required. Takes the following named arguments:

nick => STRING
user => STRING
realname => STRING 

            IRC connection details. Defaults can be set with the "new" or
            "configure" methods.

pass => STRING

Server password to connect with.

on_login => CODE

A continuation to invoke once login is successful.

$on_login->( $irc )

Any other arguments that are passed, are forwarded to the "connect" method if it is required; i.e. if "login" is invoked when not yet connected to the server.

$info = $irc->server_info( $key )
Returns an item of information from the server's 004 line. $key should one of

$irc->change_nick( $newnick )
Requests to change the nick. If unconnected, the change happens immediately to the stored defaults. If logged in, sends a "NICK" command to the server, which may suceed or fail at a later point.

PER-MESSAGE SPECIFICS

Because of the wide variety of messages in IRC involving various types of data the message handling specific cases for certain types of message, including adding extra hints hash items, or invoking extra message handler stages. These details are noted here.

Many of these messages create new events; called synthesized messages. These are messages created by the "Net::Async::IRC" object itself, to better represent some of the details derived from the primary ones from the server. These events all take lower-case command names, rather than capitals, and will have a "synthesized" key in the hints hash, set to a true value. These are dispatched and handled identically to regular primary events, detailed above.

If any handler of the synthesized message returns true, then this marks the primary message handled as well.

MODE (on channels) and 324 (RPL_CHANNELMODEIS) These message involve channel modes. The raw list of channel modes is parsed into an array containing one entry per affected piece of data. Each entry will contain at least a "type" key, indicating what sort of mode or mode change it is:

list The mode relates to a list; bans, invites, etc..

value The mode sets a value about the channel

bool The mode is a simple boolean flag about the channel

occupant

The mode relates to a user in the channel

Every mode type then provides a "mode" key, containing the mode character itself, and a "sense" key which is an empty string, "+", or "-".

For "list" and "value" types, the "value" key gives the actual list entry or value being set.

For "occupant" types, a "flag" key gives the mode converted into an occupant flag (by the "prefix_mode2flag" method), "nick" and "nick_folded" store the user name affected.

"boolean" types do not create any extra keys.

352 (RPL_WHOREPLY) and 315 (RPL_ENDOFWHO) These messages will be collected up, per channel, and formed into a single synthesized event called "who".

Its hints hash will contain an extra key, "who", which will be an ARRAY ref containing the lines of the WHO reply. Each line will be a HASH reference containing:

user_ident
user_host
user_server
user_nick
user_nick_folded
user_flags

353 (RPL_NAMES) and 366 (RPL_ENDOFNAMES) These messages will be collected up, per channel, and formed into a single synthesized event called "names".

Its hints hash will contain an extra key, "names", which will be an ARRAY ref containing the usernames in the channel. Each will be a HASH reference containing:

nick
flag

367 (RPL_BANLIST) and 368 (RPL_ENDOFBANS) These messages will be collected up, per channel, and formed into a single synthesized event called "bans".

Its hints hash will contain an extra key, "bans", which will be an ARRAY ref containing the ban lines. Each line will be a HASH reference

containing

mask User mask of the ban

by_nick
by_nick_folded

Nickname of the user who set the ban

timestamp

UNIX timestamp the ban was created

372 (RPL_MOTD), 375 (RPL_MOTDSTART) and 376 (RPL_ENDOFMOTD) These messages will be collected up into a synthesized event called "motd".

Its hints hash will contain an extra key, "motd", which will be an ARRAY ref containing the lines of the MOTD.

SEE ALSO

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>