tyler bot documentation

Index

1. Modules
1. Overview
2. Python Modules
3. Perl Modules
2. Hooking API (trod)
1. addhook()
2. clearhooks()
3. dohooks()
4. registerhook()
5. Table of hookable functions
3. Global utilities (tutil)
1. ircsend()
2. ircmsg()
3. ircmultimsg()
4. ircaction()
5. ircnotice()
6. ircjoin()
7. ircpart()
8. ircquit()
9. ircwho()
10. ircnick()
11. irckick()
12. irckill()
13. ircmode()
14. ircop()
15. ircban()
16. irctopic()
17. ircaway()
18. ircoper()
19. ircinvite()
20. ctcpsend()
21. ctcpmsg()
22. ctcpversion()
23. ctcpping()
24. ctcpuserinfo()
25. ctcpclientinfo()
26. ctcptime()
27. ctcpfinger()
28. tylercodestats()
4. Help Routines (thelp)
1. hashelp()
2. addhelp()
3. removehelp()
4. clearhelp()
5. gethelp()
6. helpcnt()
5. tyler API / defination (tyler)
1. class defination
2. attributes
3. operations
6. Perl Module Scripting
1. Limitations

Modules

So the question is, how can developers write modules for tyler? In this document I hope to provide enough resources so developers can easily write their own modules.

Overview

Python modules

Most of tylers modules are python modules. They are wrote in python and natively take advantage of the framework tyler provides. The minimal requirement for a module is simply, python code which does anything that doesn't require user-input from anything except an IRC network. You don't *have* to import anything and you aren't restricted in what you can do.

As part of development of Python modules for tyler, it's recommended you set the python __author__ global variable. This will allow the .author command of tyler to return author information about the module. This is strongly recommended for making a uniform program.

Lets look at an example

import tutil, trod
def helloworld_load(args, env):
	# lets... quit in our "hello" world <3
	tutil.ircquit(args["sck"], "Good bye cruel world")
trod.addhook("helloworld", "load", helloworld_load)

As soon as this module is loaded, the tyler bot will immidiately quit the IRC network with the reason "Good bye cruel world". Not only does this demonstrate how you write a very simple module using tutil and trod (documented below), but it also illustrates how you should make sure you know what the module you're loading actually does!

Lets see an even simpler example

import sys
sys.system("echo hello everyone on this system! | wall")

This module demonstrates functionality that doesn't even use the IRC bot at all - except to of course load it. It simply executes a shell command on the local machine. It broadcasts a message to all connected terminatals on the local machine saying "hello everyone on this system!". Should note that this is a GNU style command, and probably wont work on most machines, but as a demonstration I hope it conveys precise what you could potentially do with tyler modules.

Perl modules

See Perl Module Scripting

Hooking API (module: trod)

import trod

addhook()

trod.addhook(str modulename, str hookevent, function hookhandler)

• modulename MUST be the name of your module for the hooking process to run properly. if you do not set modulename to be the name of the calling module, you will cause a crash or unexpected behaviour at a later point in tyler's execution
• hookevent is the name of the event you wish to hook, below in the hookable list you will see a list of hookable events.
• hookhandler should be a reference to a function defination to be called when the event is triggered. the hookhandler has the prototype below

def myhookhandler(args, env):

clearhooks()

trod.clearhooks(str modulename)

dohooks()

trod.dohooks(str eventname, dict args, tyler env)

• eventname is the event you want to call the hooking routines for
• args is a dictionary of arguments to be supplied to the hookhandler, you should provide a valid for all of the args in the hookable list below.
• env should be a tyler instance

registerhook()

trod.registerhook(str modulename, str eventname)

• modulename MUST be the name of your module for the hooking process to run properly. if you do not set modulename to be the name of the calling module, you will cause a crash or unexpected behaviour at a later point in tyler's execution
eventname is the event name you want to register. you will use this name later when calling dohooks

import trod
def endofroutine(args, env):
	print "You are at the end of the example"
trod.registerhook("example", "endofexample")
trod.addhook("example", "endofexample", endofroutine)
trod.dohooks("endofexample", [], None)

You are at the end of the example

Table of hookable functions

This table shows all the currently hookable events, along with what arguments are supplied. The naming conversations explained next are used throughout this list.

Naming conventions

sck - a socket descriptor assocated with the event
source - a dict object that has 3 elements. source contains an element named "nick", "user", and "host" which corespond to each section of an IRC source string. However, if the source is a server, these 3 elements will not exist, instead a key named "server" will. If you are hooking anything which uses source you should always check if source.has_key("server") to determine the type of message
tberror - a traceback error string tbvalue - a traceback error value tbtype - a traceback error type target - may be a nick or a channel name
message - a data string with the assocated event
chan - a channel name
reason - a part, kick or quit reason string
server - a server name
victim - the nickname of a user in a kick or kill event
modestring - the entire mode string of a mode event. example modestring may be "+obmv kay *!*@*.com tyler"
topic - a new or existing topic string
newnick - only used in the nick even, the new nick of a source
args - used only in the docmd event, is a list of all the tokens seperated by " " after the command character
cmd - is a string that is equal to args[0] of the above named args event argument. This string represents the "command" that is being executed. Only available in the docmds hook
module - the module that has just loaded (or is being unloaded) returnpath - the entity to send commands 'to' that leads to the source of the hook trigger. that is to say, if the hook was triggered by a channel action, this is the channel, if it was triggered by a PM to the bot, this is that user

Universal arguement

Unlike most of the above, there is one arguement that is always provided, this is called caller, and identifies the hook the routine is being called from, allowing hook-handler routines to implement several hooks in one code block.

Global utilities (module: tutil)

There is a core module you can import to use various prewrote utilities (we actually would rather you used these since hooks may be added to some of these routines, allowing other modules to work properly). This module is called tutil

import tutil

ircsend()

tutil.ircsend(sck, data)

• sck is a valid IRC socket
• data is the protocol line to send

tutil.ircsend(validsocket, "NOTICE kay :it's redundant now to send notice's using ircsend() as you can now use ircnotice()")

ircmsg()

tutil.ircmsg(sck, target, message)

• sck is a valid IRC socket
• target can of course be a channel or a user (see the IRC RFC for what target can be)
• message is a message to delivery to the target. message shouldn't have any new lines in it.

tutil.ircmsg(validsck, "#nullnetwork", "howdy")

ircmultimsg()

tutil.ircmultimsg(sck, target, message)

• sck is a valid IRC socket
• target can of course be a channel or a user (see the IRC RFC for what target can be)
• message is a message to delivery to the target

tutil.ircmultimsg(validsck, "#nullnetwork", """< brennanOS> heres a conversation starter: Programming in C all day makes me wish I was coding Java instead

< brennanOS> discuss

< orbitz> coding in java makes me wish i was coding in erlang

< AtnNn> you guys code in java?

-!- AtnNn [n=welcome@dsl-*-*.aei.ca] has left ##c []""")

ircaction()

tutil.ircaction(sck, target, action)

• sck is a valid IRC socket
• target is a channel or a user.
• action is the action to have our bot do!

tutil.ircaction(validsck, "#nullnetwork", "dances with a drunk penguin")

ircnotice()

tutil.ircnotice(sck, target, message)

• sck is a valid IRC socket
• target can of course be a channel or a user (see the IRC RFC for what target can be)
• message is a message to delivery to the target. message shouldn't have any new lines in it.

tutil.ircnotice(validsck, "kay", "You have mail")

ircjoin()

tutil.ircjoin(sck, chan)

• sck is a valid IRC socket
• chan is the channel to join

tutil.ircsend(validsocket, "#tyler")

ircpart()

tutil.ircpart(sck, chan, reason)

• sck is a valid IRC socket
• chan is the channel to leave
• reason is an optional reason for the part

tutil.ircpart(validsocket, "#tyler", "tyler 2.0 development channel")

ircquit()

tutil.ircquit(sck, reason)

• sck is a valid IRC socket
• reason is an optional reason for the quit

tutil.ircquit(validsocket, "Shutting down")

ircnick()

tutil.ircnick(sck, newnick)

• sck is a valid IRC socket
• newnick is the new nickname

tutil.ircnick(validsocket, "Jack") # we all know tyler has multiple personalities!

irckick()

tutil.irckick(sck, chan, nick, reason)

• sck is a valid IRC socket
• chan is the channel to kick nick from
• nick is the nickname of the user to kick
• reason is the optional reason for the kick

tutil.irckick(validsocket, "#tyler", "b14ck", "You SUCK!") # we all know tyler has multiple personalities!

irckill()

tutil.irckill(sck, nick, reason)

• sck is a valid IRC socket
• nick is the nickname of the user to kill
• reason is the optional reason for the kill

tutil.irckill(validsocket, "victim", "You are not welcome here") # we all know tyler has multiple personalities!

ircmode()

tutil.ircmode(sck, target, modestring)

• sck is a valid IRC socket
• target is the channel or user to change the modes of, if I recall correctly IRC RFCs say you can only change your own modes with the mode command, thus target may only be a channel or tyler
• modestring is a raw mode string that set the modes, see the IRC RFC for more information

tutil.ircmode(validsocket, "#tyler", "+cm-o kay")

ircop()

tutil.ircop(sck, chan, [nicklist])

• sck is a valid IRC socket
• chan is a channel where the nicks are in
• nicklist is a list of nicks to op

tutil.ircop(validsocket, "#tyler", ["kay", "linkd", "will"])

ircban()

tutil.ircban(sck, channel, [banmasks])

• sck is a valid IRC socket
• channel is the channel
• banmasks is a with of banmasks to place bans on

tutil.ircban(validsocket, "#tyler", ["*@*.aol.com", "bannednick!*@*", "*!spam@*"])

irctopic()

tutil.irctopic(sck, chan, topic)

• sck is a valid IRC socket
• chan is the channel to set the topic of
• topic is the new topic

tutil.irctopic(validsocket, "#tyler", "tyler 2.0 development channel")

ircwho()

tutil.ircwho(sck, target)

• sck is a valid IRC socket
• target is the channel or user to 'who'

tutil.ircwho(validsocket, "#tyler")
#or
tutil.ircwho(validsocket, "kay")

ircoper()

tutil.ircoper(sck, user, opass)

• sck is a valid IRC socket
• user is the O:Line username
• opass is the O:Line password

tutil.ircoper(validsocket, "god", "stupidpass")

ircinvite()

tutil.ircinvite(sck, who, where)

• sck is a valid IRC socket
• who is who you want to invite
• where you want to invite them! duh!

tutil.ircinvite(validsocket, "#tyler", "AtnNn")

ircaway()

ctcpsend()

ctcpmsg()

ctcpversion()

ctcpping()

ctcpuserinfo()

ctcpclientinfo()

ctcptime()

ctcpfinger()

tylercodestats()

tutil.tylercodestats()

ret["nfiles"] # the number of files
ret["nlines"] # the total number of lines
ret["nbytes"] # total number of bytes

Help Routines (module thelp)

This module contains routines that control the user-help system of the bot.

import thelp

hashelp()

thelp.hashelp(module, cmd)

ret["cmd"] # the command name
ret["module"] # the module name
ret["syntax"] # the syntax summary
ret["description"] # the description of the command
ret["canviewfunc"] # a reference to a function that will calculate if the source address is authorised to see the command

def canviewfunc(source)

• module the module you want to see if has registered help for cmd
• cmd the cmd to look up

thelp.hashelp("somemodule", "somecommadname")

addhelp()

thelp.addhelp(module, cmd, syntax, cmddescription, canviewfunc = helpcanalwaysview):

• module the module register for (this you ussually be your module name)
• cmd the cmd to add help for
• syntax the simple syntax for the command. There is some conventions associated with this. For required arguements encompass them with < and > braces. For option arguements use [ and ] braces.
• cmddescription the general description for the command
• canviewfunc this is a function of the prototype specified above (def canviewfunc(source)), it should return true or false. true to allow the command to be displayed for source. false to skip it. If you don't give a function it defaults to viewable by all

thelp.addhelp("mockmodule", "tease", "tease <required nick>[,optional nick list]", "This command will tease \x1Frequired nick\x0F and all others in \x1Foption nick list \x0F")

removehelp()

thelp.removehelp(module, cmd):

clearhelp()

thelp.clearhelp(module):

gethelp()

thelp.gethelp(sck, targetsource, cmd, module):

• sck is any valid socket
• targetsource is the source of the help request - this will be sent back through this
• cmd is an optional arguement specifying what command to request the help for. If you don't want a specific command help, set this to None
• module is another optional arguement specifying a module to draw help from. If you don't care you can supply None

thelp.gethelp(validsck, {"nick": "kay", "user": "kay", "host": "localhost"}, None, "tyler")

helpcnt()

thelp.helpcnt()

print thelp.helpcnt()

tyler class documentation (module: tyler)

This is the documentation for the absolute core of tyler.

Class Diagram

Attributes

Operations

Perl Module Scripting

You heard right! You can write tyler modules in Perl! The methodology for this is slightly different than writing tyler modules in python. For instance, with the Perl tyler-modules, you have no need to "Hook" functions and events, instead, you simply create a subroutine handler for that event. tmodperl hooks all the trod events and then searchs for a perl subroutine to handle it.

Due to this, the name of your subroutines are important. To create a hook handler, you must use the following naming convention:

sub MyModuleName_EventToHook {}

Where MyModuleName MUST be the name of your perl module and EventToHook is the event name you want to handle. A list of the hookable events is given above. Arguements are given to the subroutine in the same fashion as the python modules,

So lets say we wanted to add a hook to all docmd events. This is our example routine in our test.pl module:

sub test_docmd {
	# get the args
	my @args = shift;
	my $env = shift;
	print "THE COMMAND WAS: " . $args[0]{"cmd"} . "\n";
	0;
}

You'll have to forgive the horrible Perl, I'm by no means a qualified Perl coder

Limitations

Unfortunately at time of writing, tmodperl has no way to unload/load or reload perl modules on the fly, unlike the python modules which are loading dynamically when needed. This means that the hook event unload does not exist for perl modules. In addition the parameters supplied to the load hook are difference, in that not only does it provide the modulename of the perl tyler-module, but it also provides references to various core tyler modules. See below for full breakdown of args.

Hook Event: load.
Called: when the perl tyler-module is loaded into tmodperl

• module
• tutil
• tconfig - be aware that if tconfig is reloaded from tyler, this current does not hold true for the perl modules (that I know of - haven't checked this yet)
• thelp