NAME
    Mojo::IRC - IRC Client for the Mojo IOLoop

VERSION
    0.0501

SYNOPSIS
      my $irc = Mojo::IRC->new(
                  nick => 'test123',
                  user => 'my name',
                  server => 'irc.perl.org:6667',
                );

      $irc->on(irc_join => sub {
        my($self, $message) = @_;
        warn "yay! i joined $message->{params}[0]";
      });

      $irc->on(irc_privmsg => sub {
        my($self, $message) = @_;
        say $message->{prefix}, " said: ", $message->{params}[1];
      });

      $irc->connect(sub {
        my($irc, $err) = @_;
        return warn $err if $err;
        $irc->write(join => '#mojo');
      });

      Mojo::IOLoop->start;

DESCRIPTION
    Mojo::IRC is a non-blocking IRC client using Mojo::IOLoop from the
    wonderful Mojolicious framework.

    If features IPv6 and TLS, with additional optional modules:
    IO::Socket::IP and IO::Socket::SSL.

    By default this module will only emit standard IRC events, but by
    settings "parser" to a custom object it will also emit CTCP events.
    Example:

      my $irc = Mojo::IRC->new;
      $irc->parser(Parse::IRC->new(ctcp => 1);
      $irc->on(ctcp_action => sub {
        # ...
      });

    It will also set up some default events: "ctcp_ping", "ctcp_time", and
    "ctcp_version".

    This class inherit from Mojo::EventEmitter.

EVENTS
  close
    Emitted once the connection to the server close.

  error
    Emitted once the stream emits an error.

  irc_close
    Called when the client has closed the connection.

  irc_error
    This event is used by IRC errors

  irc_err_nicknameinuse
  irc_join
      $self->$callback({
        params => ['#html'],
        raw_line => ':somenick!~someuser@1.2.3.4 JOIN #html',
        command => 'JOIN',
        prefix => 'somenick!~someuser@1.2.3.4'
      });

  irc_nick
      $self->$callback({
        params => ['newnick'],
        raw_line => ':oldnick!~someuser@hostname.com NICK :newnick',
        command => 'NICK',
        prefix => 'somenick!~someuser@hostname.com'
      });

  irc_mode
      $self->$callback({
        params => ['somenick', '+i'],
        raw_line => ':somenick!~someuser@hostname.com MODE somenick :+i',
        command => 'MODE',
        prefix => 'somenick!~someuser@hostname.com'
      });

  irc_notice
      $self->$callback({
        params => ['somenick', 'on 1 ca 1(4) ft 10(10)'],
        raw_line => ':Zurich.CH.EU.Undernet.Org NOTICE somenick :on 1 ca 1(4) ft 10(10)',
        command => 'NOTICE',
        prefix => 'Zurich.CH.EU.Undernet.Org',
      });

  irc_part
      $self->$callback({
        command => 'PART',
        params => ['#channel'],
        raw_line => ':somenick!~someuser@host PART #channel',
        prefix => 'somenick!~someuser@host',
      })

  irc_ping
      $self->$callback({
        params => [2687237629],
        raw_line => 'PING :2687237629',
        command => 'PING',
      })

  irc_privmsg
      $self->$callback({
        params => [ '#channel', 'some message' ],
        raw_line => ':nick!user@host PRIVMSG #nms :some message',
        command => 'PRIVMSG',
        prefix => 'nick!user@host',
      });

  irc_rpl_created
      $self->$callback({
        params => ['somenick', 'This server was created Thu Jun 21 2012 at 01:26:15 UTC'],
        raw_line => ':Tampa.FL.US.Undernet.org 003 somenick :This server was created Thu Jun 21 2012 at 01:26:15 UTC',
        command => '003',
        prefix => 'Tampa.FL.US.Undernet.org'
      });

  irc_rpl_endofmotd
  irc_rpl_endofnames
      $self->$callback({
        params => ['somenick', '#channel', 'End of /NAMES list.'],
        raw_line => ':Budapest.Hu.Eu.Undernet.org 366 somenick #channel :End of /NAMES list.',
        command => '366',
        prefix => 'Budapest.Hu.Eu.Undernet.org'
      });

  irc_rpl_isupport
      $self->$callback({
        params => ['somenick', 'WHOX', 'WALLCHOPS', 'WALLVOICES', 'USERIP', 'CPRIVMSG', 'CNOTICE', 'SILENCE=25', 'MODES=6', 'MAXCHANNELS=20', 'MAXBANS=50', 'NICKLEN=12', 'are supported by this server'],
        raw_line => ':Tampa.FL.US.Undernet.org 005 somenick WHOX WALLCHOPS WALLVOICES USERIP CPRIVMSG CNOTICE SILENCE=25 MODES=6 MAXCHANNELS=20 MAXBANS=50 NICKLEN=12 :are supported by this server',
        command => '005',
        prefix => 'Tampa.FL.US.Undernet.org'
      })

  irc_rpl_luserchannels
      $self->$callback({
        params => ['somenick', '13700', 'channels formed'],
        raw_line => ':Tampa.FL.US.Undernet.org 254 somenick 13700 :channels formed',
        command => '254',
        prefix => 'Tampa.FL.US.Undernet.org'
      })

  irc_rpl_luserclient
      $self->$callback({
        params => ['somenick', 'There are 3400 users and 46913 invisible on 18 servers'],
        raw_line => ':Tampa.FL.US.Undernet.org 251 somenick :There are 3400 users and 46913 invisible on 18 servers',
        command => '251',
        prefix => 'Tampa.FL.US.Undernet.org'
      });

  irc_rpl_luserme
      $self->$callback({
        params => ['somenick', 'I have 12000 clients and 1 servers'],
        raw_line => ':Tampa.FL.US.Undernet.org 255 somenick :I have 12000 clients and 1 servers',
        command => '255',
        prefix => 'Tampa.FL.US.Undernet.org'
      });

  irc_rpl_luserop
      $self->$callback({
        params => ['somenick', '19', 'operator(s) online'],
        raw_line => ':Tampa.FL.US.Undernet.org 252 somenick 19 :operator(s) online',
        command => '252',
        prefix => 'Tampa.FL.US.Undernet.org'
      });

  irc_rpl_luserunknown
      $self->$callback({
        params => ['somenick', '305', 'unknown connection(s)'],
        raw_line => ':Tampa.FL.US.Undernet.org 253 somenick 305 :unknown connection(s)',
        command => '253',
        prefix => 'Tampa.FL.US.Undernet.org'
      })

  irc_rpl_motd
  irc_rpl_motdstart
  irc_rpl_myinfo
      $self->$callback({
        params => ['somenick', 'Tampa.FL.US.Undernet.org', 'u2.10.12.14', 'dioswkgx', 'biklmnopstvrDR', 'bklov'],
        raw_line => ':Tampa.FL.US.Undernet.org 004 somenick Tampa.FL.US.Undernet.org u2.10.12.14 dioswkgx biklmnopstvrDR bklov',
        command => '004',
        prefix => 'Tampa.FL.US.Undernet.org',
      })

  irc_rpl_namreply
      $self->$callback({
        params => ['somenick', '=', '#html', 'somenick Indig0 Wildblue @HTML @CSS @Luch1an @Steaua_ Indig0_ Pilum @fade'],
        raw_line => ':Budapest.Hu.Eu.Undernet.org 353 somenick = #html :somenick Indig0 Wildblue @HTML @CSS @Luch1an @Steaua_ Indig0_ Pilum @fade',
        command => '353',
        prefix => 'Budapest.Hu.Eu.Undernet.org'
      })

  irc_rpl_welcome
      $self->$callback({
        params => ['somenick', 'Welcome to the UnderNet IRC Network, somenick'],
        raw_line => ':Zurich.CH.EU.Undernet.Org 001 somenick :Welcome to the UnderNet IRC Network, somenick',
        command => '001',
        prefix => 'Zurich.CH.EU.Undernet.Org'
      })

  irc_rpl_yourhost
      $self->$callback({
        params => ['somenick', 'Your host is Tampa.FL.US.Undernet.org, running version u2.10.12.14'],
        raw_line => ':Tampa.FL.US.Undernet.org 002 somenick :Your host is Tampa.FL.US.Undernet.org, running version u2.10.12.14',
        command => '002',
        prefix => 'Tampa.FL.US.Undernet.org'
      });

ATTRIBUTES
  ioloop
    Holds an instance of Mojo::IOLoop.

  real_host
    Will be set by "irc_rpl_welcome". Holds the actual hostname of the IRC
    server that we are connected to.

  user
    IRC username.

  nick
    IRC nick name accessor.

  server
    Server name and optionally a port to connect to. Changing this while
    connected to the IRC server will issue a reconnect.

  name
    The name of this IRC client. Defaults to "Mojo IRC".

  parser
      $self = $self->parser($obj);
      $self = $self->parser(Parse::IRC->new(ctcp => 1));
      $obj = $self->parser;

    Holds a Parse::IRC object by default.

  pass
    Password for authentication

  tls
      $self->tls(undef) # disable (default)
      $self->tls({}) # enable

    Default is "undef" which disable TLS. Setting this to an empty hash will
    enable TLS and this module will load in default certs. It is also
    possible to set custom cert/key:

      $self->tls({ cert => "/path/to/client.crt", key => ... })

    This can be generated using

      # certtool --generate-privkey --outfile client.key
      # certtool --generate-self-signed --load-privkey client.key --outfile client.crt

METHODS
  change_nick
    This will be deprecated. Use the code below instead:

      $self->write(NICK => $new_nick);

  connect
      $self->connect(\&callback);

    Will login to the IRC "server" and call &callback once connected. The
    &callback will be called once connected or if it fail to connect. The
    second argument will be an error message or empty string on success.

  ctcp
      $str = $self->ctcp(@str);

    This message will quote CTCP messages. Example:

      $self->write(PRIVMSG => nickname => $self->ctcp(TIME => time));

    The code above will write this message to IRC server:

      PRIVMSG nickname :\001TIME 1393006707\001

  disconnect
      $self->disconnect(\&callback);

    Will disconnect form the server and run the callback once it is done.

  register_default_event_handlers
      $self->register_default_event_handlers;

    This method sets up the default "DEFAULT EVENT HANDLERS" unless someone
    has already subscribed to the event.

  write
      $self->write(@str, \&callback);

    This method writes a message to the IRC server. @str will be
    concatenated with " " and "\r\n" will be appended. &callback is called
    once the message is delivered over the stream. The second argument to
    the callback will be an error message: Empty string on success and a
    description on error.

DEFAULT EVENT HANDLERS
  ctcp_ping
    Will respond to the sender with the difference in time.

      Ping reply from $sender: 0.53 second(s)

  ctcp_time
    Will respond to the sender with the current localtime. Example:

      TIME Fri Feb 21 18:56:50 2014

    NOTE! The localtime format may change.

  ctcp_version
    Will respond to the sender with:

      VERSION Mojo-IRC $VERSION

    NOTE! Additional information may be added later on.

  irc_nick
    Used to update the "nick" attribute when the nick has changed.

  irc_notice
    Responds to the server with "QUOTE PASS ..." if the notice contains
    "Ident broken...QUOTE PASS...".

  irc_ping
    Responds to the server with "PONG ...".

  irc_rpl_welcome
    Used to get the hostname of the server. Will also set up automatic PING
    requests to prevent timeout.

  irc_err_nicknameinuse
    This handler will add "_" to the failed nick before trying to register
    again.

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the terms of the Artistic License version 2.0.

AUTHOR
    Marcus Ramberg - "mramberg@cpan.org"

    Jan Henning Thorsen - "jhthorsen@cpan.org"