Scroll to navigation

Net::Async::IRC(3pm) User Contributed Perl Documentation Net::Async::IRC(3pm)

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->do_PRIVMSG( target => "YourName", text => "Hello world!" );

 $loop->run;

DESCRIPTION

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

Most of the actual IRC message handling behaviour is implemented by the parent class Net::Async::IRC::Protocol.

Most of the behaviour related to being an IRC client is implemented by the parent class Protocol::IRC::Client.

The following documentation may make mention of these above two parent classes; the reader should make reference to them when required.

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()" or "Win32::LoginName()".

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

The following methods documented with a trailing call to "->get" return Future instances.

connect

   $irc = $irc->connect( %args )->get

Connects to the IRC server. This method does not perform the complete IRC login sequence; for that see instead the "login" method. The returned Future will yield the $irc instance itself, to make chaining easier.

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 )

login

   $irc = $irc->login( %args )->get

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 )

change_nick

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

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

cap_supported

   $supported = $irc->cap_supported( $cap )

Returns a boolean indicating if the server supports the named capability.

caps_enabled

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

cap_enabled

   $enabled = $irc->cap_enabled( $cap )

Returns a boolean indicating if the client successfully enabled the named capability.

MESSAGE-WRAPPING METHODS

The following methods are all inherited from Protocol::IRC::Client but are mentioned again for convenient. For further details see the documentation in the parent module.

In particular, each method returns a Future instance.

do_PRIVMSG

do_NOTICE

   $irc->do_PRIVMSG( target => $target, text => $text )->get

   $irc->do_NOTICE( target => $target, text => $text )->get

Sends a "PRIVMSG" or "NOITICE" command.

SEE ALSO

•
<http://tools.ietf.org/html/rfc2812> - Internet Relay Chat: Client Protocol

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>
2018-07-02 perl v5.26.2