README

Berend
======

Berend is a Twisted IRC bot with SSL-support. If you use this module,
you will not have to write any of the boilerplate and instead can
focus on programming the behavior of your bot.

If you use SSL, there is no certificate checking so beware!


Usage
-----

To build a bot you need to write a bot config file (yaml) and some
plugins (simple python modules).

The default config file berend will look for is `berend.yaml`. If you
want to use a different config file, then you need to set the
`BEREND_CONFIG` environment variable to its path.

An example bot config file is included in the distribution and looks
like this:

berend.yaml:

    irc:
      host: irc.freenode.net
      ssl: true
      port: 6697
      channels:
        - berend-botje-test
      nickname: berend
      realname: Berend Botje
    # on_connect is a list of raw commands sent to the server on connect,
    # use this to identify for example:
    #
    #  on_connect:
    #    - "PRIVMSG NickServ :identify berend secret"
    plugins:
      berend.plugins.help:
      myberend.plugins.hello:

Add your plugins to the bottom. The key is the importable,
dot-separated python module name, the value is passed on to your
plugin's setup method. Look at the help plugin for a fully documented
example.

An example plugin looks like this:

myberend/plugins/hello.py:

    def setup(bot, config):
        bot.respond('hello', hello, ('hello', 'force bot to greet you'))

    def hello(bot, user, channel, msg, matches):
        bot.reply(user, channel, 'hello to you %s' % user)


See Also
--------

The bot is a Twisted IRC client. Check out the [Twisted documentation](http://twistedmatrix.com/documents/12.2.0/api/twisted.words.protocols.irc.IRCClient.html) and the [ircLogBot example](http://twistedmatrix.com/documents/current/core/howto/clients.html#auto5) for more information.

Oh and of course: [Berend Botje](http://nl.wikipedia.org/wiki/Berend_Botje_ging_uit_varen)