Hack 47 Write a Plug-in for PPF

Now that you know how to use the PircBot Plug-in Framework and configure its various plug-ins, let your creative juices flow by making your own plug-in.

PPF (PircBot Plug-in Framework) is an open source (http://opensource.org) plug-in framework built on top of the PircBot IRC API. It provides some basic functionality, such as connecting to IRC, joining channels, and some auth levels for access control. The PPF core itself doesn't really do very much at all, as the functionality comes from each of the plug-ins you use. Full details about the project, latest releases, plug-ins, documentation, and source code (via CVS) can be found at http://www.sourceforge.net/projects/ppf.

The plug-ins can be built quite easily by extending an abstract class called PPFPlugin. By inheriting the functionality of this class, a plug-in can include features such as XML configuration, and it can store persistent data, be internationalizable, and also provide dynamic online help.

This hack will show you how to create a simple plug-in and demonstrate some of the features that make it easy to do frequently performed tasks.

7.5.1 The Code

The simple plug-in will be called Simple, so create a new directory called Simple under the plugins directory. Then create the directory path for the source code under that (src/net/sourceforge/ppf/plugin/simpleplugin). You should end up with something like Figure 7-4.

Figure 7-4. The directory structure for the Simple plug-in

Now create a file called SimplePlugin.java in the simpleplugin directory:

package net.sourceforge.ppf.plugin.simpleplugin;



import net.sourceforge.ppf.PPF;

import net.sourceforge.ppf.PPFPlugin;

import net.sourceforge.ppf.util.PPFHelp;



public class SimplePlugin extends PPFPlugin {



    static final String PLUGIN_VERSION = "1.0";

    // The commands the plug-in will respond to.

    static final String COMMAND_TIME = "!time";

    static final String COMMAND_HELLO = "!hello";



    public SimplePlugin( ) {

        // Set the plug-in version information.

        setVersion(PLUGIN_VERSION);



        // Set the help responses for this plug-in.

        setHelp(COMMAND_TIME, new PPFHelp(COMMAND_TIME, 

                "Show the time of the server that the bot is running on",

                PPF.AUTH_NONE));

        setHelp(COMMAND_HELLO, new PPFHelp(COMMAND_HELLO,

                "The bot says hello back to you", PPF.AUTH_NONE));

    }



    // Respond to channel messages.

    public void onMessage(String channel, String sender, String login,

            String hostname, String message) {

            

        if(message.equalsIgnoreCase(COMMAND_TIME)) {

            String time = new java.util.Date( ).toString( );

            getBot( ).sendMessage(channel, sender +

                    ": The time where I am is currently: "+ time);

        } else if(message.equalsIgnoreCase(COMMAND_HELLO)) {

            getBot( ).sendMessage(channel, "Hi there " + sender + "!");

        }



    }



}

7.5.2 Running the Hack

PPF uses ANT (http://ant.apache.org) as its build system. The main build file has the necessary targets ready to call, so you just need to make a simple build file for the plug-in that sets the name and location of the plug-in and calls the main build file.

Make a file called build.xml in the new plug-in directory. An easy way of doing this is to copy an existing one from another plug-in and change the contents so it looks like this:

<?xml version="1.0"?>



<project basedir="." default="deploy">



    <property name = "plugin.project" value = "Simple"/>

    <property name = "plugin.name"    value = "Simple"/>



    <path id="plugin.classpath">

      <fileset dir=".">

        <include name="*.jar"/>

      </fileset>

    </path>



    <!-- Call the PPF build script to perform the build. 

    You can set the plugin-specific details here and keep 

    the PPF classpath in one place -->

    <target name="compile">

      <ant antfile="../../build.xml" target="compile.plugin" inheritRefs="true"/>

    </target>

    

    <target name="deploy" depends="compile">

      <jar jarfile="./${plugin.name}.jar" basedir="bin"/>

    </target>

</project>

Run the deploy target from the project build file and the source code will be compiled. The compiled bytecode will be placed into a JAR file in the plug-in directory named Simple.jar.

PPF now needs to be configured to load this plug-in. In PPFConfig.xml, you need to add:

<plugin load="yes">

  <name>Simple</name>

  <classname>net.sourceforge.ppf.plugin.simpleplugin.SimplePlugin</classname>

</plugin>

If PPF is not yet running, just start it and the Simple plug-in will be loaded.

If PPF is already running, you can auth as admin by entering:

/msg BotName auth adminPassword

The plug-in can then be loaded dynamically by entering:

/msg BotName loadplugin Simple

The plug-in is now ready to be used and will respond to !time and !hello:

<DeadEd> !time

<PPF> DeadEd: The time where I am is currently: Thu Mar 18 13:48:32 EET 2004

<DeadEd> !hello

<PPF> Hi there DeadEd!

7.5.3 Creating Advanced Plug-ins

This is an example of some of the things that can be achieved with the plug-in framework. All onXxx methods available from the PircBot API are passed to the plugin class. Methods are also available to assist in reading in XML configuration files, making some information persistent, viewing that information, internationalization, and dynamic help.

—Alex North

< Day Day Up >