--- name: "Net::Async::IRC" section: "3pm" platform: "linux" package: "libnet-async-irc-perl" version: "0.12-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::Async::IRC" --- # Net::Async::IRC(3pm) use IRC with "IO::Async" ## NAME "Net::Async::IRC" - use IRC with "IO::Async" ## SYNOPSIS ``` 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; ``` ## 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. If the `"sasl"` capability is requested and supported by the server, the `"login"` method will use that. ## METHODS The following methods documented in an `"await"` expression return Future instances. ### connect ``` $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. - 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 = await $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. 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 ) ``` If the `"sasl"` capability was requested and is supported by the server, this will be used instead of the simple `"USER/PASS"` command combination. At the current version, only the `"PLAIN"` SASL mechanism is supported. ### 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 ``` await $irc->do_PRIVMSG( target => $target, text => $text ); await $irc->do_NOTICE( target => $target, text => $text ); ``` Sends a `"PRIVMSG"` or `"NOITICE"` command. ## SEE ALSO - • \ - Internet Relay Chat: Client Protocol ## AUTHOR Paul Evans \