AnyEve...nection(3pm)

💖 AnyEve...nection — the manual page, but make it make sense 💖

okay bestie, this is AnyEvent::IRC::Connection from the User Contributed Perl Documentation crew — your girl is about to walk you through it like we're texting at 2am 🦋

---

✨ NAME ✨

AnyEvent::IRC::Connection — it's an IRC connection abstraction. that's the whole name, no notes, she's serving exactly what she says on the tin 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready, no cap:

use AnyEvent;
use AnyEvent::IRC::Connection;

my $c = AnyEvent->condvar;

my $con = new AnyEvent::IRC::Connection;

$con->connect ("localhost", 6667);

$con->reg_cb (
   connect => sub {
      my ($con) = @_;
      $con->send_msg (NICK => 'testbot');
      $con->send_msg (USER => 'testbot', '*', '0', 'testbot');
   },
   irc_001 => sub {
      my ($con) = @_;
      print "$_[1]->{prefix} says I'm in the IRC: $_[1]->{params}->[-1]!\n";
      $c->broadcast;
   }
);

$c->wait;

like… she connects, she says hi, she waits. main character energy fr fr 👑

---

💜 DESCRIPTION 💜

this is the connection class. this is where the actual interesting stuff happens — sending and receiving IRC messages, that's her. and she also handles TCP connecting, plus she can even enable TLS. multi-talented, we love that for her 🌈

heads up bestie: CTCP support is a whole separate thing — it lives in the functions encode_ctcp and decode_ctcp, which are provided by AnyEvent::IRC::Util. not here. don't come for this page about it 🙈

---

🎀 METHODS 🎀

• $con = AnyEvent::IRC::Connection->new () — this constructor doesn't take any arguments. zero. none. she's low maintenance like that ✨

NOTE: you are free to use the hash member heap (which contains a hash) to store any associated data with this object. like retry timers, or literally anything else you want to keep near her 💅

you can also access that member via the heap method, iykyk.

• $con->connect ($host, $port [, $prepcb_or_timeout]) — she tries to open a socket to the host $host and the port $port. if an error occurred, it will die (so wrap it in eval to catch that exception, bestie, don't let it take you out 😭).

if you want to connect via TLS/SSL you have to call the enable_ssl method before to enable it. order matters, periodt.

$prepcb_or_timeout can either be a callback with the semantics of a prepare callback for the function tcp_connect in AnyEvent::Socket, or a simple number which stands for a timeout. pick your fighter 🫶

• $con->enable_ssl () — this method will enable SSL for new connections that are initiated by connect. sparkle her up 🔥
• $con->disconnect ($reason) — unregisters the connection in the main AnyEvent::IRC object, closes the sockets, and sends a 'disconnect' event with $reason as argument. she's leaving the group chat, gracefully 💀
• $con->is_connected — returns true when this connection is connected. otherwise false. that's it, that's the whole personality check ✅
• $con->heap () — returns the hash reference stored in the heap member, which is local to this connection object, and it lets you store any information you want. your little stash 🎀
• $con->send_raw ($ircline) — this method sends $ircline straight to the server with no further processing done. raw. unfiltered. she said what she said 💅
• $con->send_msg ($command, @params) — this function sends a message to the server. @ircmsg is the argument list for AnyEvent::IRC::Util::mk_msg (undef, $command, @params). that's the whole deal 🌸

---

🦋 EVENTS 🦋

these are the events emitted by this module, and bestie — they shouldn't be emitted from a module user call to event. also go read the documents Object::Event about registering event callbacks, it's required reading, no skipping 🙈

• connect => $error — this event is generated when the socket was successfully connected, or when an error occurred while connecting. the error is given as second argument ($error) to the callback then. so either she made it, or she's telling you why she didn't 😭
• disconnect => $reason — this event will be generated if the connection is somehow terminated. it will also be emitted when disconnect is called. the second argument to the callback is $reason, a string that contains a clue about why the connection terminated.

if you want to reestablish a connection, call connect again. she's not gone forever, she just needs a minute 🫶

• send => $ircmsg — emitted when a message is about to be sent. $ircmsg is an array reference to the arguments of mk_msg (see AnyEvent::IRC::Util). you may modify the array reference to change the message, or even intercept it completely by calling stop_event (see Object::Event API):

$con->reg_cb (
   send => sub {
      my ($con, $ircmsg) = @_;

      if ($ircmsg->[1] eq 'NOTICE') {
         $con->stop_event; # prevent any notices from being sent.

      } elsif ($ircmsg->[1] eq 'PRIVMSG') {
         $ircmsg->[-1] =~ s/sex/XXX/i; # censor any outgoing private messages.
      }
   }
);

look at her filtering her own messages. iconic behavior 🔥

• sent => @ircmsg — emitted when a message (@ircmsg) was sent to the server. @ircmsg are the arguments to AnyEvent::IRC::Util::mk_msg. she's delivered ✨
• irc_* => $msg
• irc_<lowercase command> => $msg
• read => $msg — emitted when a message ($msg) was read from the server. $msg is the hash reference returned by AnyEvent::IRC::Util::parse_irc_msg.

Note: '<lowercase command>' stands for the command of the message in (ASCII) lower case. so like, lowercase. keep it lowercase, bestie 💅

• buffer_empty — this event is emitted when the write buffer of the underlying connection is empty and all data has been given to the kernel. see also samples/notify about a usage example 👑

Please note that this buffer is NOT the queue mentioned in AnyEvent::IRC::Client! do not confuse the two, they are different girlies, i am begging 🙈

---

💖 AUTHOR 💖

Robin Redeker, "<elmex@ta-sa.org>" — shoutout to Robin, the original icon 🎀

---

🌈 SEE ALSO 🌈

• AnyEvent::IRC
• AnyEvent::IRC::Client

go read those too, bestie, they're the extended universe 🦋

---

⭐ COPYRIGHT & LICENSE ⭐

Copyright 2006-2009 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay and that's the whole page, no cap. this was perl v5.34.0, dated 2022-06-06, from the User Contributed Perl Documentation besties — love you, go connect to something 💅💖✨