NAME
    "Net::Async::IRC" - Use IRC with "IO::Async"

SYNOPSIS
     TODO

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.

CONSTRUCTOR
  $irc = Net::Async::IRC->new( %args )
    Returns a new instance of a "Net::Async::IRC" object. This object
    represents a connection to a single IRC server. As it is a subclass of
    "IO::Async::Stream" its constructor takes any arguments for that class,
    in addition to the parameters named below.

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

    on_message => CODE
            A CODE reference to the generic message handler; see "MESSAGE
            HANDLING" below.

    on_message_* => CODE
            Any parameter whose name starts with "on_message_" can be
            installed as a handler for a specific message, in preference to
            the generic handler. See "MESSAGE HANDLING".

    pingtime => NUM
            Amount of quiet time, in seconds, after a message is received
            from the server, until a "PING" will be sent to check it is
            still alive.

    pongtime => NUM
            Timeout, in seconds, after sending a "PING" message, to wait for
            a "PONG" response.

    on_ping_timeout => CODE
            A CODE reference to invoke if the server fails to respond to a
            "PING" message within the given timeout.

             $on_ping_timeout->( $irc )

    on_pong_reply => CODE
            A CODE reference to invoke when the server successfully sends a
            "PONG" in response of a "PING" message.

             $on_pong_reply->( $irc, $lag )

            Where $lag is the response time in (fractional) seconds.

    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 "set_nick". Changing the other properties will not take
            effect until the next login.

    encoding => STRING
            If supplied, sets an encoding to use to encode outgoing messages
            and decode incoming messages.

METHODS
  $connect = $irc->is_connected
    Returns true if a connection to the server is established. Note that
    even after a successful connection, the server may not yet logged in to.
    See also the "is_loggedin" method.

  $loggedin = $irc->is_loggedin
    Returns true if the server has been logged in to.

  $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->send_message( $message )
    Sends a message to the server from the given "Net::Async::IRC::Message"
    object.

  $irc->send_message( $command, $prefix, @args )
    Sends a message to the server directly from the given arguments.

  $irc->send_ctcp( $prefix, $target, $verb, $argstr )
    Shortcut to sending a CTCP message. Sends a PRIVMSG to the given target,
    containing the given verb and argument string.

  $irc->send_ctcprely( $prefix, $target, $verb, $argstr )
    Shortcut to sending a CTCP reply. As "send_ctcp" but using a NOTICE
    instead.

  $me = $irc->is_nick_me( $nick )
    Returns true if the given nick refers to that in use by the connection.

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

    *       host

    *       version

    *       usermodes

    *       channelmodes

  $value = $irc->isupport( $key )
    Returns an item of information from the server's "005 ISUPPORT" lines.
    Traditionally IRC servers use all-capital names for keys.

  $cmp = $irc->cmp_prefix_flags( $lhs, $rhs )
    Compares two channel occupant prefix flags, and returns a signed integer
    to indicate which of them has higher priviledge, according to the
    server's ISUPPORT declaration. Suitable for use in a "sort()" function
    or similar.

  $cmp = $irc->cmp_prefix_modes( $lhs, $rhs )
    Similar to "cmp_prefix_flags", but compares channel occupant "MODE"
    command flags.

  $flag = $irc->prefix_mode2flag( $mode )
    Converts a channel occupant "MODE" flag (such as "o") into a name prefix
    flag (such as "@").

  $mode = $irc->prefix_flag2mode( $flag )
    The inverse of "prefix_mode2flag".

  $name_folded = $irc->casefold_name( $name )
    Returns the $name, folded in case according to the server's
    "CASEMAPPING" "ISUPPORT". Such a folded name will compare using "eq"
    according to whether the server would consider it the same name.

    Useful for use in hash keys or similar.

  $classification = $irc->classify_name( $name )
    Returns "channel" if the given name matches the pattern of names allowed
    for channels according to the server's "CHANTYPES" "ISUPPORT". Returns
    "user" if not.

  $nick = $irc->nick
    Returns the current nick in use by the connection.

  $nick_folded = $irc->nick_folded
    Returns the current nick in use by the connection, folded by
    "casefold_name" for convenience.

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

MESSAGE HANDLING
    Every incoming message from the IRC server causes a sequence of message
    handling to occur. First, the message is parsed, and a hash of data
    about it is created; this is called the hints hash. The message and this
    hash are then passed down a sequence of potential handlers.

    Each handler indicates by return value, whether it considers the message
    to have been handled. Processing of the message is not interrupted the
    first time a handler declares to have handled a message. Instead, the
    hints hash is marked to say it has been handled. Later handlers can
    still inspect the message or its hints, using this information to decide
    if they wish to take further action.

    A message with a command of "COMMAND" will try handlers in following
    places:

    1.  A CODE ref in a parameter called "on_message_COMMAND"

         $on_message_COMMAND->( $irc, $message, \%hints )

    2.  A method called "on_message_COMMAND"

         $irc->on_message_COMMAND( $message, \%hints )

    3.  A CODE ref in a parameter called "on_message"

         $on_message->( $irc, 'COMMAND', $message, \%hints )

    4.  A method called "on_message"

         $irc->on_message( 'COMMAND', $message, \%hints )

    Certain commands are handled internally by methods on the base
    "Net::Async::IRC" class itself. These may cause other hints hash keys to
    be created, or to invoke other handler methods. These are documented
    below.

  Message Hints
    The following keys will be present in any message hint hash:

    handled => BOOL
            Initially false. Will be set to true the first time a handler
            returns a true value.

    prefix_nick => STRING
    prefix_user => STRING
    prefix_host => STRING
            Values split from the message prefix; see the
            "Net::Async::IRC::Message" "prefix_split" method.

    prefix_name => STRING
            Usually the prefix nick, or the hostname in case the nick isn't
            defined (usually on server messages).

    prefix_is_me => BOOL
            True if the nick mentioned in the prefix refers to this
            connection.

    Added to this set, will be all the values returned by the message's
    "named_args" method. Some of these values may cause yet more values to
    be generated.

    If the message type defines a "target_name":

    *       target_type => STRING

            Either "channel" or "user", as returned by "classify_name".

    *       target_is_me => BOOL

            True if the target name is a user and refers to this connection.

    Finally, any key whose name ends in "_nick" or "_name" will have a
    corresponding key added with "_folded" suffixed on its name, containing
    the value casefolded using "casefold_name". This is for the convenience
    of string comparisons, hash keys, etc..

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.

  NOTICE and PRIVMSG
    Because "NOTICE" and "PRIVMSG" are so similar, they are handled together
    by synthesized events called "text", "ctcp" and "ctcpreply". Depending
    on the contents of the text, and whether it was supplied in a "PRIVMSG"
    or a "NOTICE", one of these three events will be created.

    In all cases, the hints hash will contain a "is_notice" key being true
    or false, depending on whether the original messages was a "NOTICE" or a
    "PRIVMSG", a "target_name" key containing the message target name, a
    case-folded version of the name in a "target_name_folded" key, and a
    classification of the target type in a "target_type" key.

    For the "user" target type, it will contain a boolean in "target_is_me"
    to indicate if the target of the message is the user represented by this
    connection.

    For the "channel" target type, it will contain a "restriction" key
    containing the channel message restriction, if present.

    For normal "text" messages, it will contain a key "text" containing the
    actual message text.

    For either CTCP message type, it will contain keys "ctcp_verb" and
    "ctcp_args" with the parsed message. The "ctcp_verb" will contain the
    first space-separated token, and "ctcp_args" will be a string containing
    the rest of the line, otherwise unmodified. This type of message is also
    subject to a special stage of handler dispatch, involving the CTCP verb
    string. For messages with "VERB" as the verb, the following are tried.
    "CTCP" may stand for either "ctcp" or "ctcpreply".

    1.  A CODE ref in a parameter called "on_message_CTCP_VERB"

         $on_message_CTCP_VERB->( $irc, $message, \%hints )

    2.  A method called "on_message_CTCP_VERB"

         $irc->on_message_CTCP_VERB( $message, \%hints )

    3.  A CODE ref in a parameter called "on_message_CTCP"

         $on_message_CTCP->( $irc, 'VERB', $message, \%hints )

    4.  A method called "on_message_CTCP"

         $irc->on_message_CTCP( 'VERB', $message, \%hintss )

    5.  A CODE ref in a parameter called "on_message"

         $on_message->( $irc, 'CTCP VERB', $message, \%hints )

    6.  A method called "on_message"

         $irc->on_message( 'CTCP VERB', $message, \%hints )

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

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

