iRCbot Plug-in Writing Guide

***************************************
*    iRCbot Plug-in Writing Guide     *
*                                     *
*            last updated             *
*             may 18 2011             *
***************************************



==============================
VERSION HISTORY
==============================

v 1       - may 18 2011 - may 18 2011
----------- Finished writing the guide. It's all here, everything I
            could think of to include. All variables currently
            defined, arrays, functions, etc... it should help those
            who wish to create a plug-in for iRCbot to do so.

            I even included templates to help you get started.

v 1.0.1   - may 18 2011
----------- Fixed some minor errors.




==============================
Table of Contents
==============================

   1.   Introduction
      1.1   How iRCbot works
      1.2   Commands and parameters
   2.   Core features
      2.1   Functions
      2.2   Variables
      2.3   Arrays
   3.   Making a plug-in
      3.1   Help parameter
      3.2   Requiring a certain level
      3.3   Relaying errors









--------------------------------------------------------------------------------------------
1.   Introduction
--------------------------------------------------------------------------------------------

          1.1   How iRCbot Works

iRCbot is a modular IRC bot written in PHP. iRCbot uses plug-ins
which extend upon it's core functionality. This guide is meant to
explain how to create plug-ins for iRCbot, but first we must know
how iRCbot works.

It is assumed that you have an understanding of PHP as all
plug-ins must be written in it. It is not required that you be an
expert with it, as long as you have a decent understanding of
how to use it for what you want to achieve with it in your
plug-in.

iRCbot is essentially a one piece program, meaning that it is
perfectly capable of running on its own. Plug-ins extend the
functionality of iRCbot by providing it with more capabilities
than just idling in a channel and stalking the users.

Basically, iRCbot alone can only connect to the server, join the
default channels and then idle. All other functionality is provided
through plug-ins which are executed by commands that users
send to iRCbot through a PRIVMSG, which if you're unfamiliar
with IRC, is either a query to iRCbot or a message sent in a
channel which iRCbot is present.

          1.2   Commands and parameters

All commands are recognized by a ~ (tilde). The command must
be started at the beginning of a PRIVMSG for it to be recognized
by iRCbot.

All commands use the file name of the plug-in in the plug-in
directory where iRCbot is stored. You cannot change the name of
a command unless the plug-in file's name is changed as well,
at least at this time.

Sample command:

~test donkey kong

In the above sample, we have the command (~test) and two
parameters (donkey, kong).

Parameters do not always have to be required for a command.
If a plug-in requires two parameters, then two parameters should
be returned, ignoring others unless otherwise specified.

Some plug-ins, such as say, use an infinite amount of parameters,
not one of which are required but the first.

It's a bit difficult to explain without seeing an already made plug-in,
but we'll get to that point later in this guide.

So far, you know that a command is what executes a plug-in and
that they share the same name, and that plug-ins may have up to
any number of parameters depending on the circumstances.

Let's say you want to add a user to a list... let's use the adduser
plug-in as a reference:

You want to add a user to the list along with a numeric value for
the user's level. You create a plug-in that will be executed by the
command ~adduser. You need to get the nick of the user as well
as the level you want to add the user as having, so you require
two parameters to ~adduser:

~adduser <nick> <level>

Parameter <nick> will contain the nickname of the user, and
parameter <level> will contain the numeric value for the level.

Now that you know how plug-ins are executed, let's learn how
to make the most of them!









--------------------------------------------------------------------------------------------
2.   Core features
--------------------------------------------------------------------------------------------

          2.1   Functions

iRCbot contains a number of ready made functions that make
the life of an iRCbot plug-in creator easier. Gone are the worries
of meddling with the IRC protocol, as difficult and daunting a
task that it isn't.

The functions that you will likely be using the most is the privmsg()
function, which is what iRCbot uses to send messages to a
channel or nick (whichever works).

All functions must be used in this fashion:

$this->functionnamehere();

The reason for this is because of the way iRCbot is designed. As
a plug-in, you are directly adding to iRCbot's class. iRCbot is
in a continuous loop state until a command is thrown its way,
which then if the plug-in exists, it executes the plug-in until the
end and then it goes back into its loop state.

$this-> signifies that it is part of the class. iRCbot is an object
so to speak, and since the functions are defined within
the object, you have to signify that you want to use them in
this object... I might be wrong as I'm fairly new to object
oriented programming, but that's how I would explain it
and that's how I did!

Anyway, here's a list of the currently available functions and
how to use them:

privmsg($channel, $message)
   Sends $message to $channel. $channel can be either a
   channel name or a nick.

action($channel, $message)
   Sends an action command containing $message to
   $channel. An action command is essentially a /me
   command.

nick($name)
   Changes the nick of iRCbot to $name if it is not already
   in use.

kick($nick, $message = null)
   Kicks $nick out of the channel it's called from. $message
   is an optional parameter, but if used will use a custom
   kick message instead of the default one.

join($channel)
   Joins $channel. If $channel is an array, it joins all of the
   channels in the array... if possible, that is.

part($channel)
   Leaves (or parts) $channel. If no channel is specified, it
   parts the channel from which it was called.

quit($message)
   Disconnects from the server with an optional custom quit
   $message. iRCbot's default quit message is "My time has
   come...".

notice($nick, $message)
   Sends a notice containing $message to $nick. $nick can
   also be a channel instead.

send($type, $param = null)
   Sends raw data to the server. Basically useful if you want
   to do something that a function can't or when there is
   no function that does what you want to do. $type is the
   IRC command, such as PRIVMSG or something similar,
   and $param is an optional parameter. As it is optional,
   $param doesn't have to be used and $type can be the
   only parameter used.

          2.2   Variables

iRCbot contains a number of variables and arrays that contain
data from the server to make your life easier. Most variables and
arrays contain specific data that has been parsed from the main
buffer to make it easier on plug-in creators to create plug-ins, so
they don't have to know how to get the information themselves
from the raw buffer data.

Unlike functions, no variables require $this-> prior to the variable
name. Here's a sample variable call:

$channel

It's obvious and easy, and all of the variables have self-explanatory
names so you'll know what they contain.

Here is the list of pre-defined variables and what they contain:

$channel
   Contains the channel which the command was received. If it
   was received via query to iRCbot, it returns iRCbot's current
   nickname. The functions privmsg and action take this into
   account so it is not necessary to check for this if using those
   functions.

$nick
   Contains the nick of the person that used a command.

$name
   Contains the username of the person that used a command.

$host
   Contains the hostmask of the person that used a command,
   but does not include the nick or username portions of of the
   hostmask, and only that after @.

$level
   Contains the level of the user that used a command. Returns
   nothing if the user is not in the user list.

$call_help
   Indicates whether the -help parameter was used. Returns 1 if
   so, otherwise returns 0.

$data
   The buffer. Contains raw data received from the socket with a
   maximum size of 512 bytes.

          2.3   Arrays

Arrays have the same use as variables, but some arrays do indeed
use $this->. However, all of the arrays that have been made to make
your job easier do not require $this->. Here's an example of calling an
array:

$parameter[0]

As you should already know, arrays start at 0 increase in value by 1
for each value within the array.

Here is the list of pre-defined arrays and the information they contain:

$command
   Contains the command called. Value starts at 1 rather than 0.

$parameter
   Contains the parameter(s) after a command. Value starts at 0.
   Pretty much contains everything that is said after a command.

$default_chan
   Contains the list of channels that iRCbot joins on startup.

$plugins
   Contains the list of loaded plug-ins. Is automatically updated
   when a plug-in is loaded.

$users
   Contains the list of users and their levels. In the array, value 0
   is the user and value 1 is the level. It follows this pattern for all
   users in the list.

$ignored
   Contains the list of users currently being ignored by iRCbot.

$this->full_data
   Contains the data from the buffer, but is exploded by whitespace.
   Not necessary unless wanting to achieve something that iRCbot's
   core functionality cannot.









--------------------------------------------------------------------------------------------
3.   Making a plug-in
--------------------------------------------------------------------------------------------

          3.1   Help parameter

It is not required for a plug-in to respond to a -help parameter,
but it is good if it does as users who want to know what it does
and how to use it will be able to find out by using it.

A help parameter is used like so:

~command -help

iRCbot checks whether the parameter is used before if executes
the plug-in, and it is not recognized if not used as the only
parameter.

When the -help parameter is used, it sets the variable $call_help
to 1 before the plug-in is executed. It is up to the plug-in to check
if $call_help is true (1 is true, 0 is false) and then act accordingly.

If you wish to acknowledge the help parameter, you may do so
however you like, but it is encouraged that you use (or at least
follow) this basic template:

<?php

$usage = "Use: ~command <parameter>";
$info = "This is information on what the plug-in does and how it works.";

if($call_help)
{
     $this->privmsg($channel, $usage);
     $this->privmsg($channel, $info);
}
else
{
     // Plug-in code goes here
}

?>

          3.2   Requiring a certain level

Some plug-ins, depending on what it does, might be best if use
is restricted to users with a certain minimum level. Users that are
not on the user list or whose level is less than the minimum
required level will not be able to use it. This is good if the plug-in
does something that you don't want everyone to be able to do,
such as changing the topic of a channel, kicking a user, etc...

As there is no limit to the level one can have, it is best if you
check if a user's level is greater than or equal to the desired
minimum level, rather than just equal to. This allows users with
a higher level than the required level to use the plug-in. I hope
that you already knew that, though.

Here is a template that you can use for a plug-in which requires
the minimum level of 150.

<?php

$usage = "Use: ~command <parameter>";
$info = "This is information on what the plug-in does and how it works.";

if($call_help)
{
     $this->privmsg($channel, $usage);
     $this->privmsg($channel, $info);
}
elseif($level >= 150)
{
     // Plug-in code goes here
}
else
{
     $this->privmsg($channel, "Can't let you do that, $nick.");
}

?>

          3.3   Relaying errors

Sometimes a user won't use a plug-in properly, but if it doesn't
say what's wrong, they won't know! It's not required that you
relay messages telling the user what they did wrong, but it
providesa better user experience and also helps for debugging
your plug-in.

It's best to check to make sure that parameters are not empty,
or at least the parameters required. You can relay specific
messages to the user when one is empty so they know what
it was they did wrong. This is just an example of when to relay
a message containing an error or what happened that was
wrong.