Net::Async::IRC(3pm)

💖 NAME 💖

Net::Async::IRC — bestie, this is how you do IRC with IO::Async ✨

(this is the 3pm page, from the User Contributed Perl Documentation, and yes it's giving very much perl-core energy 🌸)

---

✨ 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 🦋

Okay so this object class is the whole async IRC client situation — it implements an asynchronous IRC client for use in programs that are based on IO::Async. Literally the whole point. 💅

Most of the actual IRC message handling behaviour? That's implemented by the parent class Net::Async::IRC::Protocol. She's the one doing the heavy lifting.

Most of the behaviour related to being an IRC client — the client of it all — is implemented by the parent class Protocol::IRC::Client. Two parents, two icons. 👑

The following documentation may make mention of these above two parent classes; the reader should make reference to them when required. (i.e. bestie, if you need the deep lore, go read those. iykyk 🫶)

---

🎀 PARAMETERS 🎀

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

• nick => STRING
• user => STRING
• realname => STRING

Connection details, periodt. See also connect and 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(). Not me letting the system decide who you are 😭

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 — so lowkey they just sit there waiting their turn, no cap.

• 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. She's asking nicely, but only for what's on the list.

If the sasl capability is requested and supported by the server, the login method will use that. Fancy auth arc. 🔥

---

🌈 METHODS 🌈

The following methods documented in an await expression return Future instances. Futures, bestie. They come back to you later. 🦋

💜 connect

$irc = await $irc->connect( %args );

Connects to the IRC server. Important: 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. She hands you back herself. Main character energy fr fr. ✨

• 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. Slay, no more shouting your password at the void.

At the current version, only the PLAIN SASL mechanism is supported. That's the only flavour on the menu, bestie. 🍓

🌸 change_nick

$irc->change_nick( $newnick );

Requests to change the nick. If unconnected, the change happens immediately to the stored defaults — instant, iconic, no waiting. If logged in, sends a NICK command to the server, which may suceed or fail at a later point. So like, we'll find out. 🙈

---

👑 IRC v3.1 CAPABILITIES 👑

The following methods relate to IRC v3.1 capabilities negotiations. It's giving diplomacy. 🎀

💅 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. Rude of the server, honestly.

⭐ cap_supported

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

Returns a boolean indicating if the server supports the named capability. Yes/no, true/false, slay/not-slay.

🧚 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. Periodt.

---

🎀 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. (Go read the parent module for the full tea, bestie. 🫶)

In particular, each method returns a Future instance. Every single one. Futures everywhere. 🦋

💜 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 🌈

• http://tools.ietf.org/html/rfc2812 — Internet Relay Chat: Client Protocol. The sacred text. Read it and you too will be obsessed. ✨

---

💜 AUTHOR 💜

Paul Evans <leonerd@leonerd.org.uk> — king behaviour, honestly. 👑

---

and that's the whole page, bestie 💖 this was perl v5.32.1, dated 2021-12-29, and the manual is Net::Async::IRC(3pm) — go forth and async, you absolute icon 🎀✨🦋