User Manual

Copyright © 2004, 2005 Riku Nurminen

Permission is granted to make and distribute verbatim copies of this manual provided the above copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Table of Contents

1. New commands for adding, listing and deleting scripts

For oer to be able to find your scripts you must place them under the scripts/ subdirectory of the directory where oer was started from.

2. The scripting API

oerperl scripts work by means of callbacks (or handlers). You register a handler (i.e. a Perl sub) for some specific event, and then oer will call that handler whenever the event arrives.

There are 5 types of callbacks/handlers:

You can interact with oer from any of the above handlers by using the various API methods.

2.1. Startup and shutdown callbacks

Startup and shutdown callbacks can be used for doing initialization and cleanup within a script. The callbacks can be registered with the OerPerl::register_startup_callback and OerPerl::register_shutdown_callback methods.

Note that unlike event and command handlers and timers you can only register a single startup and a single shutdown callback per script. Re-registering a startup or a shutdown callback will override the previously registered one for that script.

Example: 

my $version = "1.0";

OerPerl::register_startup_callback("my_startup_callback");
OerPerl::register_shutdown_callback("my_shutdown_callback");

sub my_startup_callback
{
    if(OerPerl::DEBUG) {
        OerPerl::oer_debug(OerPerl::DEBUG_INFO,
            "my_startup_callback()->myscript.pl version $version\n");

    }
}

sub my_shutdown_callback
{
    # do some cleanup
}

2.2. Event handlers

Event handlers can be used to receive raw server messages (e.g. PRIVMSG, JOIN, QUIT, NICK, 301, 313, ...).

A new event handler can be registered with the OerPerl::add_event_handler method. You can have as many event handlers as you want, but keep in mind that having hundreds of them will eventually slow oer down.

An event handler is passed 4 parameters which are the tokens from the raw line sent by the IRC server. Consider the following two IRC events:

-!- Rakkis [rakkis@geek1.rakkis.net] has joined #test
<Rakkis> Hello, World!

The above will produce the following two raw lines:

:Rakkis!rakkis@geek1.rakkis.net JOIN :#test
:Rakkis!rakkis@geek1.rakkis.net PRIVMSG #test :Hello, World!

Assuming we have registered an event handler for both JOIN and PRIVMSG event types, our event handler will receive the following parameters:

$prefix = "Rakkis!rakkis@geek1.rakkis.net"
$command = "JOIN"
$params = "#test"
$trailing = ""

and:

$prefix = "Rakkis!rakkis@geek1.rakkis.net"
$command = "PRIVMSG"
$params = "#test"
$trailing = "Hello, World!"

Note that scripts always receive events after oer has processed them.

Example: 

OerPerl::add_event_handler("PRIVMSG", "my_event handler");

sub my_event handler
{
    my($prefix, $command, $params, $trailing) = @_;
    my @user = ();
    my $tochan = 1;

    # See if this PRIVMSG came from a channel or directly to us (private query)
    if(!OerPerl::is_valid_channel($params)) {
        @user = split(/!/, $prefix);
        $tochan = 0;
    }

    # Send the PRIVMSG back to wherever we got it
    OerPerl::sendto($tochan ? $params : $user[0],
        $tochan ? OerPerl::CHANNEL : OerPerl::USER,
        "got PRIVMSG: $prefix $command $params :$trailing");
}

2.3. Command handlers

Command handlers can be used to implement new commands and/or to override/block the existing oer commands.

A new command handler can be registered with the OerPerl::add_command_handler method. You can have as many command handlers as you want, but keep in mind that having hundreds of them will eventually slow oer down.

Registering a command handler for a command that already exists in oer will cause your command handler to be called first. After that the normal oer command will be run, unless your command handler returns OerPerl::BLOCK_OER_COMMAND, in which case the oer command will be blocked.

Here’s a command handler example for new command (“hello”) and a blocking command (“uptime”; note the return value): 

OerPerl::add_command_handler("hello", "my_commandhandler_hello");
OerPerl::add_command_handler("uptime", "my_commandhandler_uptime");

sub my_commandhandler_hello
{
    my($command, $target, $nick, $userhost, $args) = @_;
    my $tochan = OerPerl::is_valid_channel($target) ? 1 : 0;
    my $target_type = $tochan ? OerPerl::CHANNEL : OerPerl::USER;

    # Reply to the channel / user where this command came from
    OerPerl::sendto($tochan ? $target : $nick, $target_type, "Hello, World!");
}

sub my_commandhandler_uptime
{
    my($command, $target, $nick, $userhost, $args) = @_;
    my $tochan = OerPerl::is_valid_channel($target) ? 1 : 0;
    my $target_type = $tochan ? OerPerl::CHANNEL : OerPerl::USER;
    my $uptime;

    $uptime = `uptime`;

    # Reply to the channel / user where this command came from
    OerPerl::sendto($tochan ? $target : $nick, $target_type, "uptime: $uptime");

    # Return the block value to stop oer from executing the normal 'uptime'
    # command. If you commented this out, then oer would reply with both the
    # system's uptime and it's own uptime (in that order).
    return OerPerl::BLOCK_OER_COMMAND;
}

2.4. Timers

Timers can be used for executing a script sub at specific, constant intervals. You can add a timer with the OerPerl::add_timer method. You can have as many timers as you want, but keep in mind that having hundreds of them will eventually slow oer down.

Note that the minimum timer interval is 1 second. 

OerPerl::add_timer(60, "my_timer");

sub my_timer
{
    # do something every 1 minute
}