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",
     )->get;

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

    use_caps => ARRAY of STRING
            Attempts to negotiate IRC v3.1 CAP at connect time. The array
            gives the names of capabilities which will be requested, if the
            server supports them.

METHODS
  $irc->connect( %args ) ==> $irc
    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.

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

  $irc->connect( %args )
    The following additional arguments are used to provide continuations
    when not returning a Future.

    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 )

  $irc->login( %args ) ==> $irc
    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.

    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->login( %args )
    The following additional arguments are used to provide continuations
    when not returning a Future.

    on_login => CODE
            A continuation to invoke once login is successful.

             $on_login->( $irc )

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

IRC v3.1 CAPABILITIES
    The following methods relate to IRC v3.1 capabilities negotiations.

  $caps = $irc->caps_supported
    Returns a HASH whose keys give the capabilities listed by the server as
    supported in its `CAP LS' response. If the server ignored the `CAP'
    negotiation then this method returns `undef'.

  $supported = $irc->cap_supported( $cap )
    Returns a boolean indicating if the server supports the named
    capability.

  $caps = $irc->caps_enabled
    Returns a HASH whose keys give the capabilities successfully enabled by
    the server as part of the `CAP REQ' login sequence. If the server
    ignored the `CAP' negotiation then this method returns `undef'.

  $enabled = $irc->cap_enabled( $cap )
    Returns a boolean indicating if the client successfully enabled the
    named capability.

MESSAGE HANDLING
SEE ALSO
    *   http://tools.ietf.org/html/rfc2812 - Internet Relay Chat: Client
        Protocol

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