NAME

Mojo::IRC - IRC Client for the Mojo IOLoop

VERSION

0.06

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.

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.

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

change_nick

This will be deprecated. Use the code below instead:

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

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.

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

To install Mojo::IRC, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mojo::IRC

CPAN shell

perl -MCPAN -e shell
install Mojo::IRC

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

TESTING

EVENTS

close

error

irc_close

irc_error

irc_err_nicknameinuse

irc_join

irc_nick

irc_mode

irc_notice

irc_part

irc_ping

irc_privmsg

irc_rpl_created

irc_rpl_endofmotd

irc_rpl_endofnames

irc_rpl_isupport

irc_rpl_luserchannels

irc_rpl_luserclient

irc_rpl_luserme

irc_rpl_luserop

irc_rpl_luserunknown

irc_rpl_motd

irc_rpl_motdstart

irc_rpl_myinfo

irc_rpl_namreply

irc_rpl_welcome

irc_rpl_yourhost

ATTRIBUTES

ioloop

name

nick

parser

pass

real_host

server

tls

user

METHODS

change_nick

connect

ctcp

disconnect

register_default_event_handlers

write

DEFAULT EVENT HANDLERS

ctcp_ping

ctcp_time

ctcp_version

irc_nick

irc_notice

irc_ping

irc_rpl_welcome

irc_err_nicknameinuse

COPYRIGHT

AUTHOR

Module Install Instructions