README

NAME
    Bot::BasicBot::Pluggable - extended simple IRC bot for pluggable modules

SYNOPSIS
  Creating the bot module
      # with all defaults.
      my $bot = Bot::BasicBot->new();

      # with useful options. pass any option
      # that's 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)],

                    );

  Running the bot (simple)
    There's a shell script installed to run the bot.

      $ bot-basicbot-pluggable --nick MyBot --server irc.perl.org

    Then connect to the IRC server, /query the bot, and set a password. See
    Bot::BasicBot::Pluggable::Module::Auth for further details.

  Running the bot (advanced)
    There are two useful ways to create a Pluggable bot. The simple way is:

      # 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();

    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:

      # Load the Loader module.
      $bot->load('Loader');

      # run the bot.
      $bot->run();

    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:

      !load Auth
      !auth admin julia
      !password julia new_password
      !auth admin new_password

    Once you've done this, your bot is safe from other IRC 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.

      !load Seen
      !load Google
      !load Join

    The Join module lets you tell the bot to join and leave channels:

      <botname>, join #mychannel
      <botname>, leave #someotherchannel

    The perldoc pages for the various modules will list other commands.

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 seperate. You can have seperate modules
    for factoid tracking, 'seen' status, karma, googling, etc. Included
    default modules are below. Use "perldoc
    Bot::BasicBot::Pluggable::Module::<module name"> for help on their
    individual terminology.

      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.

    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 IRC
    /query). The modules receive events when the bot sees things happen and
    can, in turn, respond. See "perldoc Bot::BasicBot::Pluggable::Module"
    for the details of the module API.

METHODS
    new(key => value, ...)
        Create a new Bot. Except of the additional attributes loglevel and
        logconfig identical to the "new" method in Bot::BasicBot. Please
        refer to their accessor for documentation.

    load($module)
        Load a module for the bot by name from "./ModuleName.pm" or
        "./modules/ModuleName.pm" in that order if one of these files exist,
        and falling back to "Bot::BasicBot::Pluggable::Module::$module" if
        not.

    reload($module)
        Reload the module $module - equivalent to unloading it (if it's
        already loaded) and reloading it. Will stomp the old module's
        namespace - warnings are expected here. Not toally clean - if you're
        experiencing odd bugs, restart the bot if possible. Works for minor
        bug fixes, etc.

    unload($module)
        Removes a module from the bot. It won't get events any more.

    module($module)
        Returns the handler object for the loaded module $module. Used,
        e.g., to get the 'Auth' hander to check if a given user is
        authenticated.

    modules
        Returns a list of the names of all loaded modules as an array.

    available_modules
        Returns a list of all available modules whether loaded or not

    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.

    remove_handler($handler_name)
        Remove a handler with the given name.

    store
        Returns the bot's object store; see Bot::BasicBot::Pluggable::Store.

    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.

    loglevel
        Returns the bots loglevel or sets it if an argument is supplied. It
        expects trace, debug, info, warn, error or fatal as value.

    logconfig
        Returns the bot configuration file for logging. Please refer to
        Log::Log4perl::Config for the configurations files format. Setting
        this to a differant file after calling init() has no effect.

        Returns or set

    dispatch($method_name, $method_params)
        Call the named $method on every loaded module with that method name.

    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.

    run Runs the bot. POE core gets control at this point; you're unlikely
        to get it back.

BUGS
    During the "make", "make test", "make install" process, POE will moan
    about its kernel not being run. This is a "Bot::BasicBot problem",
    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.

REQUIREMENTS
    Bot::BasicBot::Pluggable is based on POE, and really needs the latest
    version. Because POE 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.

LICENSE
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR
    Mike Eldridge <diz@cpan.org>

    I am merely the current maintainer; however, the AUTHOR heading is
    traditional.

CONTRIBUTORS
    * Mario Domgoergen <mdom@cpan.org>

    * Tom Insam <tom@jerakeen.org>

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.

    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.

    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.

SEE ALSO
    * POE

    * POE::Component::IRC

    * Bot::BasicBot

    * Infobot: http://www.infobot.org/

    * Mozbot: http://www.mozilla.org/projects/mozbot/