Brad Stewart and Danny DiPaolo 
Moobot User Manual 

--- Meta 
-- Who Should Read This? 
This document is intended primarily for anyone who is running/admining a 
moobot, though the information herein will also be of use to anyone who 
frequents a channel inhabited by a moobot.

-- What Is Covered? 
My intent in writing this is to give people not familiar with what moobot is 
and how it works a heads up on how to run, use and administer it.  The included 
moduels, permission system, and module interface are discussed.

-- What's Not covered? 
This isn't intended to be an installation/setup howto, for that check the 
installation manual, which should be available in the same place you got this 
document.

-- Latest Version 
The latest version of this document can be retrieved from the moobot project 
site at http://sourceforge.net/projects/moobot

--- Introduction 
-- Who We Are 
The two primary developers on this project, Brad Stewart and Danny DiPaolo, 
are college students who also happen to be IRC addicts.  Though we are 
responsible for the core development, others help by writing modules, 
reporting bugs, and all that good stuff.  If you ever want to chat, one or 
both of us can usually be found on irc.openprojects.net in #moobot or 
#grasshoppers.  We go by Bradmont and Strike, respectively.

-- Why We Are Doing This 
As I've already mentioned, we're IRC addicts.  At one point, the previous host 
of the IRC bot that lived in a channel we both frequent (a blootbot) took down 
his server, and the bot with it.  At this point, I stepped in, downloaded the 
latest blootbot release, and suffered through its install and configuration.  

Running this bot was a bit of a hastle, with semi-frequent breakages, functions
that didn't work, and all sorts of other joys.  Because it's written in perl, 
debugging any errors I found was no easy task.  Anyway, to make a long story 
even longer, one day we got to talking about the problems with the blootbot, 
and thought it might be fun to create our own.  We registered a project on 
sourceforge, and then quite happily let it sit, untouched, for five months.

So eventually, during one Christmas vacation, we got back to talking about the 
moobot, and did a bit of playing.  We stumbled upon a nice library, irclib, 
written by Joel Rosdahl.  This provided all the networking/protocol code for 
us, as well as a basic ircbot class, from which we built the initial revision 
of moobot.  Though the current moobot uses this library set as its base, we 
have plans to redo the whole foundation of the bot, but that's going to take 
awhile.

Anyway, after about 3 days straight hacking, we had a reasonably usable bot, 
which has evolved since then into what it is today.  Enjoy. :-)

-- WTF is moobot? 
You've probably inferred this from that intro, but it's an IRC bot written in 
Python (the language of the gods, thank you very much Guido).  It's intended 
to be similar to blootbot (from a user's standpoint), but much more uniform, 
normal, and managable.

--- Privileges/Grants System 
Because I'd be unable to write the rest of this document without constantly 
referring to the privs systm, I'll cover that first.

Moobot has a (reasonably) advanced privilege system, to control everything 
from joining/parting channels to ignoring troublesome users.  A privilege is 
granted to a nick/hostmask (eg, Bradmont!bradmont@*.cc.shawcable.net) and 
anyone who matches that hostmask gets the priv.  For this reason, be very 
selective about what hostmasks you give a privilege to.

The current privileges are:

all_priv:  This counts as every privilege (except notalk_priv).  You likely 
only want to give this priv to yourself, and possibly others who you absolutely 
trust to have full power over the bot.

grant_priv:  grant_priv allows a person to grant other privileges they have 
(including grant_priv) to anyone else.  You will also want to be careful with 
this one.

delete_priv:  delete_priv gives a user the ability to delete any factoid in 
the database, whether they created it or not.

lock_priv: This priv lets a user lock or unlock any factoid in the database 
(normally you can only lock factoids that match your nick, and unlock ones 
you've locked)

notalk_priv: notalk_priv causes the bot to totally ignore everything a given 
user says.

join_priv:  Users with join_priv can tell the bot to join channels.

part_priv:  Users with part_priv can tell the bot to part channels.

nick_priv:  This priv lets the grantee tell the bot to change it's nick.

kick_priv:  kick_priv gives a user the power to have the bot kick someone from 
a channel (provided the bot is opped in that channel, of course).

add_lart_priv: With this priv, a user can add larts, praises and dunnos to the database.

poll_priv:  This priv allows users to create, alter and delete polls.

reset_stats_priv:  With this priv, a user can reset a user's stats (eg, 
hehstats, lolstats, karma).

faketell_priv: Normally, when you get the bot to tell (user) about (factoid), 
the bot will do so, and send the message in a format like ``Bradmont wanted 
you to know:  foo is bar.''  with this priv, you can use the alternate 
``faketell,'' which will remove the ``Bradmont wanted you to know:'' from the 
beginning of the message, making it look sort of like the bot is talking of 
its own accord.


--- IRC Functions 

What follows is a fairly comprehensive description of a few of the
more popular functions included with Moobot.  It is in no way intended
to be comprehensive of all modules, as that number continues to grow.
Eventually we hope to implement an online help system that makes the
modules self-documenting and reduces the amount of documentation we
have to write.

-- Join/Part 
To have the bot join or part a channel, give it the command ``join #channel'', 
eg, ``moobot: join #grasshoppers''.  This can be done in public or via a 
privmsg directly to the bot.  Parting works exactly the same, ``moobot: part 
#channel''.  To do these two actions, you need join_priv and part_priv, 
respectively (or all_priv, of course).

-- Kicking 
Ever want to kick someone but you didn't have ops?  Well, now you
can!  You just have to have your bot with ops in that channel.
Simply tell your bot ``kick #channel nick'' and it will kick the
user specified by ``nick'' out of #channel.  You need kick_priv
to do this.

--- Factoids 
Factoids are one of the main reasons we wanted a bot in our channel.
It's easy to store useful (or not so useful) information for ALL to
read by simply telling the bot about it and then either having the bot
tell them later or letting them discover it in whatever way they
choose.

-- Requesting Factoids 
If you know the name of the factoid of that you wish to see, then
simply address the bot with the factoid key and it will return the
value for you.  Some factoids contain special groups which get
chosen randomly, such as ``(foo|bar)'', which will get parsed to
choose either ``foo'' or ``bar'' when a factoid is requested.  To
see the actual factoid value without any of this parsing taking
place, you simply address the bot with ``literal <factoid name>''.

-- Adding Factoids 
Factoids are added by simply telling the bot ``foo is bar'' (of
course, addressing it either explicitly with the bot name or with
the shorthand addressing style).  Of course, a number of things
can happen as a result of this.  The factoid may already exist,
which the bot will then tell you.  Otherwise, the factoid will be
added to the bot's factoid database.  By default, anyone can add
factoids, but if they are ignored, they cannot.

Note: as naming convention goes, ``foo'' is called the ``factoid
key'' and ``bar'' is the ``factoid value''.

-- Deleting Factoids 
Factoids are removed by simply telling the bot to either ``forget''
or ``delete'' the factoid key.  If the person has delete_priv and
the factoid is not locked, it will be removed.

-- Locking and Unlocking Factoids 
To lock a factoid the person who requests it must either have
lock_priv or the factoid key they are trying to lock must be
their nick.  This allows people to have factoids of their own even
without having special privileges.  To do this, they simply need
to tell the bot ``lock foo'' where ``foo'' is the factoid key they
wish to lock.  Unlocking adheres to the same set of rules except
that you use ``unlock'' instead of ``lock''.

-- Replacing Factoids 
Factoids can be replaced if the person requesting it has
delete_priv.  To do this, simply tell the bot ``no <factoid key>
is <new factoid>'' and it will replace the factoid for that
factoid key with your new factoid text.  We use delete_priv for
this because the mechanism behind it is implemented by simply
deleting the factoid and recreating it.

-- Modifying Factoids 
If a small portion of a factoid's value is fit to be changed, it
can be done without replacing the entire factoid using simple
regular expressions.  To do this, simply tell the bot ``<factoid
value> =  <set of regular expressions to apply, in order>''.  For
example, if I set the factoid ``foo'' to have the value ``bar'', I
can make it read ``blatz'' by telling the bot ``foo = 
s/bar/blatz/''

-- Searching Factoids 
You can search the factoids database in a number of ways.  You can
search by factoid key, factoid value, or author (substrings of
each).

- Search by key 
Obviously if you know what a factoid key is, you can simply
request the factoid as described above.  If you want to see
which factoid keys contain a certain substring, simply use the
``listkeys'' function to do that.  If you want to see all keys
with ``foo'' in the name, simply address the bot with
``listkeys foo'' and it will list up to 15 distinct keys that
have that substring in it, with a total count of how many do
have that substring.

- Search by value 
If you know what a factoid contains, but aren't sure what the
factoid key is, you can use the ``listvalues'' function to
find the factoid you are looking for.  If you want to find the
factoid which contains a certain word or phrase, simply
address the bot with ``listvalues <phrase to search for>'' and
it will display up to 15 distinct keys that contain that
phrase as well as displaying a total count of keys that
contain that phrase.

- Search by author 
You can see what factoids a certain user has created by
searching for their name or nickmask using the ``listauth''
command.  Simply address the bot with ``listauth <author name
or substring>'', and it will display results as described in
the previous two search sections.

-- Requesting Factoid Info 
A variety of information about each factoid is stored, ranging
from who authored to the factoid, to when it was created, to who
locked it if anyone, to how many times it has been requested, etc.
To get this information use the ``factinfo'' function.  Simply
address the bot with ``factinfo <factoid key>'' and you will be
greeted with a plethora of factoid information.

--- Larts, Punishes, and Praises 
Lart is an abbreviation of the ``Luser Attitude Readjustment Tool'',
an idea we got from the blootbot we used to use.  To use this against
something or someone else (or even yourself), simply address the bot
with the ``lart'' or ``punish'' command: ``(lart|punish) <whatever>''.
You can optionally add a reason for the lart, by appending ``for
<reason>''.  The action that the bot takes will describe the reason as
well.  The actions (larts) that the bot dishes out are retrieved from
a table in the bot's database, and chosen at random.

Alternatively, you can do something nice for someone or something by
using the ``praise'' tool.  The syntax is exactly the same as above
except using the ``praise'' command instead of ``lart'' or ``punish''.

-- Adding Larts 
If a user has the add_lart_priv, they can add a lart to the
bot's database.  The syntax for doing so is to address the bot
with ``add lart <lart text>''.  The lart text should reference the
object of the lart using the text ``WHO'' for whatever is to be
larted/punished.  For example, ``add lart pulls WHO's pants down''
would result in someone getting larted having their pants pulled
down by the bot.

Praises are added in the same manner, but with ``add praise''
instead of ``add lart'', although it still requires
add_lart_priv.

--- Channel Statistics 
These modules fit more into the ``fun'' category, and really 
aren't particularly useful.  but they're fun.

-- Hehstats, et al 
This module counts the number of times a user has said
any of the special keywords it's set up to listen for.  The
initial word it listened for was ``heh''.  The count is kept
by a user's nickname, and stored in the database.  A word is
only counted when it is the soul contents of a message to a
channel.  To view the top 3 counts for a particular
statistic, use the ``hehstats'' command, substituting for
``heh'' the name of the statistic you want to check.

If a user is abusing the stats, for instance by repeatedly
saying ``heh'' to bring their stats up, a bot admin can use
the ``hehreset'' command, in the form ``moobot: hehreset 
Bradmont'' and that persons' stats of that type will be set
to zero.  You can also use this for resetting someone's
karma.

-- Quotes/Webstats 
This module counts the total number of times a person has
spoken in each channel, and store a random quote for that
person.  The chances of a new quote replacing the old is
ten in the total number of times that person has spoken in
the channel, so the quotes change less and less often the
more someone speaks.  To get the quote for a user in the
current channel, use ``moobot:  quote Bradmont''.  This
module was written to keep statistics to be put on a
website -- we have CGIs that display the stats, but I'm not
sure if/when we're going to release them.

--- 'Net Lookup 
These modules create connections to external servers 
(mostly via HTTP, but not always) to look up information.

-- Google 
This module searches google and returns a list of URLs
(a maximum of 5) for the results.  Syntax is like this:
``moobot:  google for a big cow''.

-- Slashdot 
By saying to the bot ``moobot: slashdot'', the bot will
download the current slashdot headlines, and print them to
the channel.

-- Kernel 
This module displays the latest versions of various Linux
kernel releases.  It uses the output from the finger daemon
running on kernel.org (try ``finger @kernel.org'' in your
favourite unix shell).  Syntax:  ``moobot: kernel''.

-- Insults 
This module generally makes fun of things.  It gets a random
insult and then applies it to the target specified by the
user.  An example:
<Bradmont> moobot: insult perl
<moobot> perl is nothing but a dread-bolted gob of unintelligent slurpee-backwash.

-- Excuses 
This will get you a random, tech related excuse.  Syntax:
``moobot: excuse''.

-- Dict 
This implements a simple client for the ``dict'' protocol.  It
connects to dict.org and looks up the meaning of a given word.
Syntax:  ``moobot: dict foo''.

-- Version 
A quick lookup for the version of any software package that
exists in the freshmeat database.  Example:
<Bradmont> moobot: version python
<moobot> Latest version of python according to [fm]: 2.2.1c1

-- Dns Lookup 
Uses the DNS server of the bot's host machine to resolve
either a DNS  name into an ip address, or vice versa.
Syntax:  ``moobot: nslookup sourceforge.net''.

-- Stock Quotes 
This module returns the current price of a stock, by the
company's symbol (I don't know what those things are supposed
to be called...  I'm not into the whole stock market scene)
Example:
<Bradmont> moobot: stockquote rhat
<moobot> The current price of RHAT is 5.95

--- Miscellaneous 

-- Run-Time Module Reloading 
When debugging moobot modules, you often have to test them
a number of times to fix all the errors.  This used to mean
that every change you made required that the bot be restarted,
which can take time, since its IRC connection has to be killed
and restarted, the bot must be reinitialized, and so forth.

However, MooBot now has the ability to reload its modules at
run-time, so you won't have to restart it nearly so often.
To reload a single module, use ``moobot: reload *modulename*''.
The bot will reload just that one module.  To reload all modules,
simply use ``moobot: reload''.  Only users with all_priv may
use these functions.

MooBot does not currently have the ability to load new modules
at run-time, but it's coming.

--- Customizing/Writing Modules 
See the Module Author Guide included with this distribution.

--- Bugs 
Probably the easiest way to contact us with bug reports is to simply hop on 
IRC and join us in #moobot on irc.openprojects.net and if we are around, tell 
us what problems you are having and we might even test it right then and there.

