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.

  $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.

  RPL_WHOREPLY and 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

  RPL_NAMEREPLY and 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

  RPL_BANLIST and 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

  RPL_MOTD, RPL_MOTDSTART and 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
    *   http://tools.ietf.org/html/rfc2812 - Internet Relay Chat: Client
        Protocol

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

