.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Bot::BasicBot::Pluggable 3pm" .TH Bot::BasicBot::Pluggable 3pm "2013-10-29" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bot::BasicBot::Pluggable \- extended simple IRC bot for pluggable modules .SH "VERSION" .IX Header "VERSION" version 0.98 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Creating the bot module" .IX Subsection "Creating the bot module" .Vb 2 \& # with all defaults. \& my $bot = Bot::BasicBot\->new(); \& \& # with useful options. pass any option \& # that\*(Aqs valid for Bot::BasicBot. \& my $bot = Bot::BasicBot::Pluggable\->new( \& \& channels => ["#bottest"], \& server => "irc.example.com", \& port => "6667", \& \& nick => "pluggabot", \& altnicks => ["pbot", "pluggable"], \& username => "bot", \& name => "Yet Another Pluggable Bot", \& \& ignore_list => [qw(hitherto blech muttley)], \& \& ); .Ve .SS "Running the bot (simple)" .IX Subsection "Running the bot (simple)" There's a shell script installed to run the bot. .PP .Vb 1 \& $ bot\-basicbot\-pluggable \-\-nick MyBot \-\-server irc.perl.org .Ve .PP Then connect to the \s-1IRC\s0 server, /query the bot, and set a password. See Bot::BasicBot::Pluggable::Module::Auth for further details. .SS "Running the bot (advanced)" .IX Subsection "Running the bot (advanced)" There are two useful ways to create a Pluggable bot. The simple way is: .PP .Vb 4 \& # Load some useful modules. \& my $infobot_module = $bot\->load("Infobot"); \& my $google_module = $bot\->load("Google"); \& my $seen_module = $bot\->load("Seen"); \& \& # Set the Google key (see http://www.google.com/apis/). \& $google_module\->set("google_key", "some google key"); \& \& $bot\->run(); .Ve .PP The above lets you run a bot with a few modules, but not change those modules during the run of the bot. The complex, but more flexible, way is as follows: .PP .Vb 2 \& # Load the Loader module. \& $bot\->load(\*(AqLoader\*(Aq); \& \& # run the bot. \& $bot\->run(); .Ve .PP This is simpler but needs further setup once the bot is joined to a server. The Loader module lets you talk to the bot in-channel and tell it to load and unload other modules. The first one you'll want to load is the 'Auth' module, so that other people can't load and unload modules without permission. Then you'll need to log in as an admin and change the default password, per the following /query: .PP .Vb 4 \& !load Auth \& !auth admin julia \& !password julia new_password \& !auth admin new_password .Ve .PP Once you've done this, your bot is safe from other \s-1IRC\s0 users, and you can tell it to load and unload other installed modules at any time. Further information on module loading is in Bot::BasicBot::Pluggable::Module::Loader. .PP .Vb 3 \& !load Seen \& !load Google \& !load Join .Ve .PP The Join module lets you tell the bot to join and leave channels: .PP .Vb 2 \& , join #mychannel \& , leave #someotherchannel .Ve .PP The perldoc pages for the various modules will list other commands. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Bot::BasicBot::Pluggable started as Yet Another Infobot replacement, but now is a generalised framework for writing infobot-type bots that lets you keep each specific function separate. You can have separate modules for factoid tracking, 'seen' status, karma, googling, etc. Included default modules are below. Use \f(CW\*(C`perldoc Bot::BasicBot::Pluggable::Module:: for help on their individual terminology. .PP .Vb 10 \& Auth \- user authentication and admin access. \& DNS \- host lookup (e.g. nslookup and dns). \& Google \- search Google for things. \& Infobot \- handles infobot\-style factoids. \& Join \- joins and leaves channels. \& Karma \- tracks the popularity of things. \& Loader \- loads and unloads modules as bot commands. \& Seen \- tells you when people were last seen. \& Title \- gets the title of URLs mentioned in channel. \& Vars \- changes module variables. .Ve .PP The way the Pluggable bot works is very simple. You create a new bot object and tell it to load various modules (or, alternatively, load just the Loader module and then interactively load modules via an \s-1IRC\s0 /query). The modules receive events when the bot sees things happen and can, in turn, respond. See \&\f(CW\*(C`perldoc Bot::BasicBot::Pluggable::Module\*(C'\fR for the details of the module \s-1API.\s0 .SH "METHODS" .IX Header "METHODS" .IP "new(key => value, ...)" 4 .IX Item "new(key => value, ...)" Create a new Bot. Except of the additional attributes loglevel and logconfig identical to the \f(CW\*(C`new\*(C'\fR method in Bot::BasicBot. Please refer to their accessor for documentation. .IP "load($module)" 4 .IX Item "load($module)" Load a module for the bot by name from \f(CW\*(C`./ModuleName.pm\*(C'\fR or \&\f(CW\*(C`./modules/ModuleName.pm\*(C'\fR in that order if one of these files exist, and falling back to \f(CW\*(C`Bot::BasicBot::Pluggable::Module::$module\*(C'\fR if not. .IP "reload($module)" 4 .IX Item "reload($module)" Reload the module \f(CW$module\fR \- equivalent to unloading it (if it's already loaded) and reloading it. Will stomp the old module's namespace \- warnings are expected here. Not totally clean \- if you're experiencing odd bugs, restart the bot if possible. Works for minor bug fixes, etc. .IP "unload($module)" 4 .IX Item "unload($module)" Removes a module from the bot. It won't get events any more. .IP "module($module)" 4 .IX Item "module($module)" Returns the handler object for the loaded module \f(CW$module\fR. Used, e.g., to get the 'Auth' hander to check if a given user is authenticated. .IP "modules" 4 .IX Item "modules" Returns a list of the names of all loaded modules as an array. .IP "available_modules" 4 .IX Item "available_modules" Returns a list of all available modules whether loaded or not .ie n .IP "add_handler($handler_object, $handler_name)" 4 .el .IP "add_handler($handler_object, \f(CW$handler_name\fR)" 4 .IX Item "add_handler($handler_object, $handler_name)" Adds a handler object with the given name to the queue of modules. There is no order specified internally, so adding a module earlier does not guarantee it'll get called first. Names must be unique. .IP "remove_handler($handler_name)" 4 .IX Item "remove_handler($handler_name)" Remove a handler with the given name. .IP "store" 4 .IX Item "store" Returns the bot's object store; see Bot::BasicBot::Pluggable::Store. .IP "log" 4 .IX Item "log" Logs all of its argument to loglevel info. Please do not use this function in new code, it's simple provided as fallback for old modules. .IP "loglevel" 4 .IX Item "loglevel" Returns the bots loglevel or sets it if an argument is supplied. It expects trace, debug, info, warn, error or fatal as value. .IP "logconfig" 4 .IX Item "logconfig" Returns the bot configuration file for logging. Please refer to Log::Log4perl::Config for the configurations files format. Setting this to a different file after calling \fIinit()\fR has no effect. .Sp Returns or set .ie n .IP "dispatch($method_name, $method_params)" 4 .el .IP "dispatch($method_name, \f(CW$method_params\fR)" 4 .IX Item "dispatch($method_name, $method_params)" Call the named \f(CW$method\fR on every loaded module with that method name. .IP "help" 4 .IX Item "help" Returns help for the ModuleName of message 'help ModuleName'. If no message has been passed, return a list of all possible handlers to return help for. .IP "run" 4 .IX Item "run" Runs the bot. \s-1POE\s0 core gets control at this point; you're unlikely to get it back. .SH "BUGS" .IX Header "BUGS" During the \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make test\*(C'\fR, \f(CW\*(C`make install\*(C'\fR process, \s-1POE\s0 will moan about its kernel not being run. This is a \f(CW\*(C`Bot::BasicBot problem\*(C'\fR, apparently. Reloading a module causes warnings as the old module gets its namespace stomped. Not a lot you can do about that. All modules must be in Bot::Pluggable::Module:: namespace. Well, that's not really a bug. .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" Bot::BasicBot::Pluggable is based on \s-1POE,\s0 and really needs the latest version. Because \s-1POE\s0 is like that sometimes. You also need POE::Component::IRC. Oh, and Bot::BasicBot. Some of the modules will need more modules, e.g. Google.pm needs Net::Google. See the module docs for more details. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "AUTHOR" .IX Header "AUTHOR" Mike Eldridge .PP I am merely the current maintainer; however, the \s-1AUTHOR\s0 heading is traditional. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 2 Mario Domgoergen .IP "\(bu" 2 Tom Insam .IP "\(bu" 2 David Precious .SH "CREDITS" .IX Header "CREDITS" Bot::BasicBot was written initially by Mark Fowler, and worked on heavily by Simon Kent, who was kind enough to apply some patches we needed for Pluggable. Eventually. Oh, yeah, and I stole huge chunks of docs from the Bot::BasicBot source too. I spent a lot of time in the mozbot code, and that has influenced my ideas for Pluggable. Mostly to get round its awfulness. .PP Various people helped with modules. Convert was almost ported from the infobot code by blech. But not quite. Thanks for trying... blech has also put a lot of effort into the chump.cgi & chump.tem files in the examples/ folder, including some /inspired/ calendar evilness. .PP And thanks to the rest of #2lmc who were my unwilling guinea pigs during development. And who kept suggesting totally stupid ideas for modules that I then felt compelled to go implement. Shout.pm owes its existence to #2lmc. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 2 \&\s-1POE\s0 .IP "\(bu" 2 POE::Component::IRC .IP "\(bu" 2 Bot::BasicBot .IP "\(bu" 2 Infobot: http://www.infobot.org/ .IP "\(bu" 2 Mozbot: http://www.mozilla.org/projects/mozbot/