Perlbot Plugins
===============



1) Introduction and description of what a plugin is
---------------------------------------------------

Everyone who runs an IRC bot has a different set of requirements.  There
will always be someone who feels that a given set of features is too much
or too little for their purposes.  This is why we decided to keep the core
perlbot functionality limited to a small set of things that nearly
*everyone* will want in a bot, and added a 'plugin' feature to accommodate
all the extras.  (See perlbot.txt for a description of what a stock
perlbot with no plugins can do.)

A plugin is a small package which adds some small bit of functionality to
your perlbot.  It is meant to easily 'plug in' to an existing perlbot
installation with little or no effort.  Here are some examples of what a
plugin could do:

- add an interface to pull the most recent headlines from a given news
  website
- add an interface to a web search engine or other form-based webpage
- allow IRC users to play interactive games with the bot, such as a trivia
  or quiz game
- add an interface to a specific unix utility or other program, such as
  ispell (spell checker) or bc (calculator)
- provide protection for channels, to prevent takeovers, flooding and
  other abuses



2) Layout of plugin directory
-----------------------------

All plugins reside in a subdirectory under your perlbot directory (we'll
refer to the perlbot directory as "perlbot/" here) called "plugins".  You
can change this location if you want, by changing the bot.plugindir
option in the main perlbot configuration file, but we'll always refer to
it as "plugins" here.  Each plugin resides completely in its own directory
under "perlbot/plugins", and the directory is simply the name of the
plugin.  So if you had a plugin called "Foo", it would reside in the
directory "perlbot/plugins/Foo".



3) Installing a plugin
----------------------

A plugin will come as a .tar.gz or possibly .zip archive.  To install it,
go to your perlbot plugins directory and extract the archive.  The archive
should expand into a directory which has the same name as the plugin, as
described above in Section 2. Read the README file in that directory, if
there is one.  If the README instructs you to modify your main perlbot
configuration file or the plugin's configuration file, make the necessary
modifications.  Now just start perlbot (if it's already running, make sure
to stop it first) and your shiny new plugin will be enabled.



4) Disabling a plugin
---------------------

To prevent perlbot from automatically loading a plugin when it starts, add a
line to the 'bot' section of your config file with the word 'noload' followed
by the name of the plugin that you wish to disable.  For example, if you want
to prevent the "Foo" plugin from being loaded, you would add the line
"noload Foo".  The plugin will not be immediately unloaded from your perlbot,
but it will not be loaded at the next startup.


5) Dynamically loading a plugin
-------------------------------

You can even tell your perlbot to load a plugin that is currently not loaded.
Simply message the bot "#plugins load PluginName" where PluginName is the name
of the plugin you want to load.  You can also use "start" instead of "load" if
that's easier to remember.  If the plugin you loaded is one of the "noload"
plugins (see section 4) then it will still be prevented from loading the next
time you start perlbot.  If you want the plugin to automatically start up,
you'll have to remove the appropriate "noload" line from your config file.

