NAME
Mojo::IRC - IRC Client for the Mojo IOLoop
VERSION
0.27
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
The module Test::Mojo::IRC is useful if you want to write tests without
having a running IRC server.
MOJO_IRC_OFFLINE (from v0.20) is now DEPRECATED in favor of
Test::Mojo::IRC.
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. Default to "user".
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. Defaults to current logged in user or falls back to
"anonymous".
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 and update the "nick" attribute.
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"