NAME

Mojo::IRC - IRC Client for the Mojo IOLoop

VERSION

0.13

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.

TESTING

Set MOJO_IRC_OFFLINE to allow testing without a remote host. Example:

BEGIN { $ENV{MOJO_IRC_OFFLINE} = 1 }
use Mojo::Base -strict;
use Mojo::IRC;
use Test::More;

my $irc = Mojo::IRC->new(nick => 'batman', server => 'test.com');
$irc->parser(Parse::IRC->new(ctcp => 1));

$irc->on(
  ctcp_avatar => sub {
    my($irc, $message) = @_;
    $irc->write(
      NOTICE => $message->{params}[0],
      $irc->ctcp(AVATAR => 'https://graph.facebook.com/jhthorsen/picture'),
    );
  }
);

$irc->from_irc_server(":abc-123 PRIVMSG batman :\x{1}AVATAR\x{1}\r\n");
like $irc->{to_irc_server}, qr{NOTICE batman :\x{1}AVATAR https://graph.facebook.com/jhthorsen/picture\x{1}\r\n}, 'sent AVATAR';
done_testing;

NOTE! from_irc_server() is only available when MOJO_IRC_OFFLINE is set.

EVENTS

close

Emitted once the connection to the server close.

error

Emitted once the stream emits an error.

err_event_name

Events that start with "err_" is emitted when there is an IRC response that indicate an error. See Mojo::IRC::Events for example events.

ctcp_event_name

Events that start with "ctcp_" is emitted if the "parser" can understand CTCP messages, and there is an CTCP response.

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

See Mojo::IRC::Events for example events.

irc_error

This event is used to emit IRC errors. It is also possible for finer granularity to listen for events such as err_nicknameinuse.

NOTE: "irc_error" events are emitted even if you listen to err_ events, but they are always emitted after the err_ event.

irc_event_name

Events that start with "irc_" is emit when there is a normal IRC response. See Mojo::IRC::Events for example events.

ATTRIBUTES

ioloop

Holds an instance of Mojo::IOLoop.

name

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

nick

IRC nick name accessor.

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

real_host

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

server

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

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

user

IRC username.

METHODS

connect

$self = $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.

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

rastaval/mojo-irc