README

yauib -- Yet Another Useless IRC Bot

Introduction
============

This bot is designed to be simple for developers.

Dependencies
============

There's only two dependencies, irclib and argparse :
  On debian, aptitude install python-irclib python-arparse
  Or easy_install python-irclib python-argparse
  Or DL them, irclib is from sourceforge http://sourceforge.net/projects/python-irclib/
              and argparse is from http://code.google.com/p/argparse/

Simple Quick Start
==================

Here is a simple quick start using my simple hooks, so you don't have
to write code.

 * Fetch it
    $ git clone git://github.com/JulienPalard/yauib.git && cd yauib

 * launch it
    $ ./ircbot.py connect 'irc.server.example.com' '#your_channel' 'your_bot_login'
    Now your bot should appear on your channel.

 * Remove the hook that say that you haven't read the README file :
    $ rm -f hooks-enabled/pubmsg

 * Select one basic hook
    Now it's the time to hook some events, let's bind the 'command' hook to
    public messages :
    $ ( cd hooks-enabled && ln -s ../hooks-available/command pubmsg )

    The 'command' hook tries to call executables in the directory
    'commands-enabled' for everything said on the channel, with the first word
    as executable name, and other as arguments, so the next step is to choose
    some commands.

 * Select some basic commands
    Let's test them all ... you'll choose later :X
    $ ( cd commands-enabled && for command in ../commands-available/*; do ln -s "$command"; done )
    /!\ Some commands will need writable directories like 'logs', 'db' or 'conf'

 * Now try your bot writing 'say hello' on the channel :
     The bot will run 'hooks-enabled/pubmsg' that points to
     'hooks-available/command'. hooks-available/commands receiving 'say
     hello' will call `commands-enabled/say hello`. say is, basically a
     shell script with 'echo $*' So it will echo hello, that will be
     wrote back by the bot on the channel.

I wanna write commands, how it works ?
======================================

If you don't want to write complicated hooks, just use my simple one,
and write commands.

You first have to bind the `command` hook to `pubmsg` and `privmsg` hooks :
  $ ( cd hooks-enabled && ln -s ../hooks-available/command pubmsg )
  $ ( cd hooks-enabled && ln -s ../hooks-available/command privmsg )

Now, for each received message, my 'command' hook will try to find an
executable in the 'advanced-commands-enabled' directory, then in the
'commands-enabled' directory, finally trying to run
'commands-enabled/run'.

So you can write commands in any language you want, just make them
read their arguments, and make them write to stdout.  A command also
can put debugging information on stderr, the information will be
logged by the bot, you can run the bot with the -vvv option to get
your debug back to the screen.

As commands are only executables, you don't have to restart the bot to
make it see them, just add the file, and bim, it works.

Advanced commands
-----------------

Advanced commands have to live in ./advanced-commands-available/
directory, create a symbolink link in the ./advanced-commands-enabled/
to make them callable for the 'command' hook, permitting you to
enable/disable a command in a few seconds.

Commands in the advanced-commands-enabled permits you to return raw
messages directly to the IRC server, permitting you to send messages,
kicks, bans, join, whatever you want, you have to understand the IRC
protocol to use them.

Basic commands
--------------
Basic commands have to live in ./commands-available/
directory, create a symbolink link in the ./commands-enabled/
to make them callable for the 'command' hook, permitting you to
enable/disable a command in a few seconds.

A basic command can only reply with text, so don't worry about IRC
protocol, don't worry about multiline responses, don't worry about
response length limit, just write something to stdout it will be sent
back to the one who called the command.

A basic command writing a calendar on the channel should be named cal,
and only contain :

#!/bin/sh
cal

I wanna write hooks, how it works ?
===================================

YAUIB is a very basic bot that, for each event received from IRC will
call a hook in the directory ./hooks-enabled/, so write your own
hooks, in every language you want.

Hooks protocol
--------------
Hooks reply can have two forms :

 * Form 1: Prefix your response by 'RAW ' and every following lines
   will be sent to the server.

 * Form 2: Prefix your response by 'MSG ', put a target (typically
   argv[3] if you wanna reply), and your response. Responses from MSG
   can follow on multiples lines, each line will be sent to the
   server, delayed from 1 second, to avoid being kiked too early for
   flood, your response will also be splitted in multiples lines if
   it's too long, so just don't worry when using this form.

On which hooks can I hook my scripts ?
--------------------------------------
Typical usefull commands are :
 * all_raw_messages : Get all messages from IRC server, do whatever you want.
     Specific parameters : Only the full message, in one parameter
 * pubmsg : Hook on public messages
     Specific parameters : Only the sentence, in one parameter
 * privmsg : Hook on private messages
     Specific parameters : Only the sentence, in one parameter

There are tons of other hooks ( > 100 ) from irclib and I didn't know
them all so watch your logs to catch those you want. (And document
their parameters here ?)

Which parameters are sent to hooks ?
------------------------------------
Parameter 1, 2, 3 and 4 are :
source login, source host, target login, and target host
followed by command-specific parameters.

There is a directory to store every hooks, that is hooks-available so you
should enable only some needed, creating symlinks in the directory
hooks-enabled.

There is a usefull default hook I wrote for you, it's named 'command'.
It executes commands that it find in the directory commands-enabled
so you have to create some symlinks from the directory commands-available
where I stored the commands I wrote.

NOTE: You don't have to restart the bot when you change / add a hook.

So a very basic 'parrot' hook should be :
#!/bin/sh
shift 4 # Drop sender login and host, target login and host
printf "%s\n" "$*"

Is there another way to make the bot speak ?
============================================

Yes, the bot is listening on a local port, by default 6668.
Everything received on this port is wrote back to the channel.
So a simple :
$ echo foo | netcat localhost 6668
will do the trick, but you should also try :
# ./ircbot.py say foo
That does the same !

With this feature you can push messages from cron, webpages or
everything else.

Conclusion
==========

Enjoy creating new hooks / commands, using your favorite language !