Content-type: text/html Manpage of dAmnBot

dAmnBot

Section: User Contributed Perl Documentation (3)
Updated: 2007-04-02
Index Return to Main Contents

NAME

dAmnBot - Framework for creating dAmn bots.

SYNOPSIS

 use dAmnBot;

 # These are default values and handlers for all options
 dAmnBot->new({
   debug => 0,
   trace => 0,
   dAmn => {
     username => '',
     password => '',
     channels => ['', ''],
     command_prefix => '!',
     handlers => {
       dAmnServer => \&handle_dAmnServer,
       login      => \&handle_login,
       join       => \&handle_misc,
       part       => \&handle_misc,
       property => {
         members     => \&handle_members,
         privclasses => \&handle_privclasses,
         title       => \&handle_title,
         topic       => \&handle_topic,
       },
       recv  => {
         msg         => \&handle_msg,
         action      => \&handle_msg,
         join        => \&handle_recv_join,
         part        => \&handle_recv_part,
         privchg     => \&handle_privchg,
         kicked      => \&handle_kick,
       },
       send       => \&handle_misc,
       ping       => \&handle_ping,
       other      => \&handle_misc,
       bot        => {
#        xyzzy => sub {
#        my ($damn, $channel) = @_;
#          $damn->damn_send($channel, "Nothing happens.");
#        },
#                       _     => sub { # default handler
#                               my ($damn, $channel, $cmd) = @_;
#                               carp "Unhandled command: $cmd!";
#                       },
       },
     }
     tablumps => {
       emote  => '{0}',
       link   => '<{0}>',
       img    => '<{cmd}:{0}>', # {cmd} is the "command"; in this case: img
       dev    => '<http://{1}.deviantart.com/> ({0}{1})',
       thumb  => '<http://www.deviantart.com/view/{0}/> (\'{1}\' by {2})',
       avatar => '<{0}>',
       br     => "\n\t",
       _      => sub { # replacements can be function references. _ is the default handler
         my ($cmd, @args) = @_;
         my $t = "<$cmd";
         $t   .= '[' . join('|', @args) . ']' if @args;
         $t   .= '>';
         return $t;
       },
     },
   },
   server => {
       host => 'chat.deviantart.com',
       port => 3900,
   },
 });

DESCRIPTION

This module provides a framework for creating a dAmn bot. It keeps an automatically update list of users connected to a given channel, and is customised by plugging in handlers for dAmn events.

HANDLERS

Handlers receive two arguments: $damn and $packet. Respectively: a reference to a dAmnBot object, and a reference to a hash containing the received packet. Where applicable, handlers also receive a third argument: $channel. Some handlers also receive a fourth, context-specific, argument:

title and topic receive the title or topic and all the recv handlers receive the 'target' of the action (username, &c).

BOT COMMANDS

Bot action handlers receive all recv=>msg events where the message begins with command_prefix. They receive four arguments: $damn, $username, $command, and @arguments.

You can also define a default handler, which will be passed all commands that don't have handlers associated with them, by adding a '_' field to the dAmn=>handlers=>bot hash.

$packet

The structure of $packet is as follows:

 $packet = {
   cmd     => $cmd,
   param   => $param,
   arg     => $arg,
   body    => @body,
   channel => $channel # recv and send events
 };

THE $damn OBJECT

The damn object contains the following methods and properties:

$damn->channels(): Returns an array containing the names of all channels dAmnBot is connected to.
$damn->channelinfo($channel): Returns the channel information structure for $channel.
$damn->members($channel): Returns the members in $channel, indexed by nick name.
$damn->privclasses($channel): Returns the privclasses in $channel, indexed by both name and id.
$damn->topic($channel)
$damn->title($channel): Return the topic/title of $channel.
$damn->username(): Returns the username of the bot.
$damn->password(): Returns the password of the bot.
$damn->authtoken(): Returns the authtoken of the bot.
$damn->damn_admin($channel, $data): Perform /admin command in $channel, with $data as argument.
$damn->damn_ban($channel, $user): In $channel: demote $user to the group with ID 1 --- i.e., ban them.
$damn->damn_demote($channel, $user, [$group]): Demote $user to $group, or if $group is omitted, demote them one step.
$damn->damn_join($channel): Join $channel (sans '#').
$damn->damn_kick($channel, $user, $reason): Kick $user for $reason.
$damn->damn_login(): Log in to the dAmn server. No arguments. You shouldn't need to use this.
$damn->damn_note($user, $subject, $body): Send $user a deviantNOTE with the subject of $subject and a body of $body.
$damn->damn_part($channel): Leave $channel (sans '#').
$damn->damn_parse_tab_lumbs($text): Parse 'tablumps' (dAmn formatting codes) in $text. Performs replacements as specified in $damn->{config}->{dAmn}->{tablumps}.
$damn->damn_pjoin($user): Join a private chat with $user. Equivalent to calling "$damn->damn_join($un lt $user ? "$un:$user" : "$user:$un");" ($un == $damn->username).
$damn->damn_pong(): Send a pong to dAmnServer. You need to call this in a ping handler or you'll be kicked off the server.
$damn->damn_promote($channel, $user, $group): Promote $user to $group in $channel. Or, if $group is omitted, promote them one step.
$damn->damn_raw_send($channel, $data): Send raw data $data to dAmnServer.
$damn->damn_send($channel, $msg): Send the message $msg in $channel. $msg can be either a string or a reference to an array of strings.
$damn->{config}: Contains all options passed to dAmnBot->new().
$damn->{heap}: A reference to the POE::Component::Client::TCP heap. You shouldn't need to access this.

LICENSE & DISCLAIMER

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

AUTHOR & COPYRIGHT

This document was created by man2html, using the manual pages.
Time: 14:30:14 GMT, April 02, 2007