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

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

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.32.1                                       2021-12-29                               Net::Async::IRC(3pm)