Net::Async::IRC - use IRC with IO::Async
Net::Async::IRC
IO::Async
use Future::AsyncAwait; 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 ); await $irc->login( nick => "MyName", host => "irc.example.org", ); await $irc->do_PRIVMSG( target => "YourName", text => "Hello world!" ); $loop->run;
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.
The following named parameters may be passed to new or configure:
new
configure
Connection details. See also connect, login.
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().
user
$ENV{LOGNAME}
getpwuid()
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.
nick
change_nick
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.
If the sasl capability is requested and supported by the server, the login method will use that.
sasl
The following methods documented in an await expression return Future instances.
await
$irc = await $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. The returned Future will yield the $irc instance itself, to make chaining easier.
$irc
Hostname of the IRC server.
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.
IO::Async::Loop
$irc->connect( %args );
The following additional arguments are used to provide continuations when not returning a Future.
Continuation to invoke once the connection has been established. Usually used by the login method to perform the actual login sequence.
$on_connected->( $irc )
Continuation to invoke in the case of an error preventing the connection from taking place.
$on_error->( $errormsg )
$irc = await $irc->login( %args );
Logs in to the IRC network, connecting first using the connect method if required. Takes the following named arguments:
IRC connection details. Defaults can be set with the new or configure methods.
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 );
A continuation to invoke once login is successful.
$on_login->( $irc )
If the sasl capability was requested and is supported by the server, this will be used instead of the simple USER/PASS command combination.
USER/PASS
At the current version, only the PLAIN SASL mechanism is supported.
PLAIN
$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.
NICK
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.
CAP LS
CAP
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.
CAP REQ
$enabled = $irc->cap_enabled( $cap );
Returns a boolean indicating if the client successfully enabled the named capability.
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.
await $irc->do_PRIVMSG( target => $target, text => $text ); await $irc->do_NOTICE( target => $target, text => $text );
Sends a PRIVMSG or NOITICE command.
PRIVMSG
NOITICE
http://tools.ietf.org/html/rfc2812 - Internet Relay Chat: Client Protocol
Paul Evans <leonerd@leonerd.org.uk>
To install Net::Async::IRC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Async::IRC
CPAN shell
perl -MCPAN -e shell install Net::Async::IRC
For more information on module installation, please visit the detailed CPAN module installation guide.