NAME

Net::IRC::OO - IRC library for Pugs

SYNOPSIS

  use Net::IRC::OO;
  
  # Create new bot object
  my Net::IRC::OO $bot .= new(
    nick     => "blechbot",
    username => "blech",      # (optional, defaults to $nick)
    ircname  => "Ingo's Bot", # (optional, defaults to $nick)
    host     => "localhost",
    port     => 6667,         # (optional)
    autoping => 90,           # (optional, defaults to 90)
    live_timeout => 120,      # (optional, defaults to 120)
    floodcontrol => 0,        # (optional, defaults to 0)
    debug_raw => 0,           # (optional, defaults to 0)
  );
  
  # Register callbacks
  $bot.add_handler("INVITE",   \&on_invite);
  $bot.add_handler("PRIVMSG",  \&on_privmsg);
  $bot.add_handler("loggedin", \&on_ready);

  # Connect and login
  $bot.connect();
  $bot.login();

  # Enter main event loop
  $bot.run();

DESCRIPTION

Net::IRC::OO is an IRC library for Pugs. Note that it is not a port of Perl 5's Net::IRC.

METHODS

Net::IRC::OO.new(...)

Creates a new bot object. See SYNOPSIS for accepted parameters.

The bot will autoping the server if it hasn't seen traffic for $autoping seconds, and it'll drop the connection if it hasn't seen traffic for $live_timeout seconds. Furthermore, it'll track its status (its nick, the channels it has joined, etc.).

$bot.login()

Tries to login, using the nickname, username, and ircname you've specified in the constructor. If the nickname is already used, this module will try to use a permuted nick (for example bot_, _bot, etc.).

$bot.run()

Starts the main runloop, which is only exited if the connection to the server dies. To read data from the server, a blocking readline call is used.

$bot.curnick, $bot.curusername, $bot.curircname, $bot.curhostname

Returns the current nickname, username, or ircname. Note that thesse are not necessarily the names you specified in the constructor. For example, this module automatically tries to use slight variations of the nickname in the login phase (for example bot_, _bot, etc.) if the desired nick is already used.

This module will /WHO itself after login, so it can give you accurate username and ircname information.

This is a readonly accessor. To set the nickname, use the nick method.

$bot.last_traffic, $bot.last_autoping

These are readonly accessors. last_traffic is the timestamp of when the last traffic from the server was seen, and last_autoping is the timestamp of the last autoping.

$bot.connected

Returns a true value if the bot's socket to the server is currently connected.

Note that you might want to use the logged_in method instead.

$bot.logged_in

Returns a true value if the bot is logged in.

$bot.channels

Returns a list of channels the bot has joined. This is a readonly accessor, you have to use the join and part methods to join or leave channels.

$bot.channel("#chan")

Returns a hashref describing #chan. Its keys are topic (the current topic) and users, a hashref, which has the nicks who are on the channel as keys. Note that the nicknames are normalized.

$bot.user("nick")

Returns a hashref describing nick. Currently, there's only one key, channels, which is a hashref, which has the channels nick has joined as keys. Note that the channel names are normalized.

$bot.add_handler("001", -> $event {...})

$bot.add_handler("JOIN", -> $event {...})

$bot.add_handler("loggedin", -> $event {...})

Adds a callback to be executed when the bot receives a corresponding message. Event names which are all lowercase are "pseudo" events. See below for a list of pseudo events.

The callback is given a $event hashref, containing:

line

The original line received from the server (unmodified).

server

The server the line was sent from. This is not necessarily the server you connected to.

to

The nick the message was sent to.

rest

Additional information (varies).

from

The nick!hostmask the message was sent from. Not available for numeric handlers.

from_nick

The nick part of from. Not available for numeric handlers.

object

The nick/channel/whatever the message operated (varies).

pseudo

The pseudo event (if appropriate).

$bot.join(channel => "#chan", key => "password")

Joins a channel (optionally using the specified key).

$bot.part("#chan")

Parts a channel.

$bot.quit("reason")

Quits the connection to the server by sending a /QUIT command. Note that the socket usually stays connected for a few seconds.

$bot.nick("newnick")

Tries to change the bot's nick. Also see nick below.

$bot.topic("#chan"), $bot.topic(channel => "#chan", topic => "new topic")

Retrieves a channel's topic or tries to set it.

$bot.kick(channel => "#chan", nick => "...", reason => "...")

Kicks somebody from a channel, stating a reason optionally.

$bot.mode(target => $nick|$channel, mode => "+o iblech")

Performs the /MODE command. Note that you can supply both a nickname and a channel name to the target parameter.

$bot.invite(channel => "#chan", target => "nick")

Invites nick to #chan.

$bot.oper(username => "...", password => "...")

Tries to gain IRC operator rights.

$bot.privmsg(to => "...", text => "..."), $bot.notice(to => "...", text => "...")

Sends a PRIVMSG or a NOTICE to a destination.

Note: A bot should always use NOTICE to send replies. Quoting RFC 1459:

  The NOTICE message is used similarly to PRIVMSG.  The difference between
  NOTICE and PRIVMSG is that automatic replies must never be sent in response
  to a NOTICE message.  This rule applies to servers too - they must not send
  any error reply back to the client on receipt of a notice.  The object of
  this rule is to avoid loops between a client automatically sending something
  in response to something it received.  This is typically used by automatons
  (clients with either an AI or other interactive program controlling their
  actions) which are always seen to be replying lest they end up in a loop with
  another automaton.

$bot.raw("...")

Sends a command to the server. The command is not modified by this module, aside from appending the correct newline characters.

PSEUDO EVENTS

loggedin

The loggedin event is fired when the bot has successfully logged in.

runloop

The runloop event is fired when an iteration of the main runloop is finished.

FLOODCONTROL

Most IRC servers disconnect you if you post too many commands in too short time.

If you supply :floodcontrol(1) to the constructor, this module won't simply send all commands immediately to the server, but creates a queue, which is then slowly sent to the server.

EXAMPLES

See examples/network/seenbot.p6, examples/network/logbot.p6 and examples/network/svnbot.p6 in the Pugs Subversion Repository for example bots using this module.

AUTHOR

Ingo Blechschmidt <iblech@web.de>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl and perlartistic for details.

cpanm Perl6::Pugs

perl -MCPAN -e shell
install Perl6::Pugs