NAME

OurNet::BBSAgent - Scriptable telnet-based virtual users

SYNOPSIS

# To run it, make sure you have a 'cvic.bbs' file in the same
# directory. Its contents is listed just below this section.

use OurNet::BBSAgent;

my $cvic = new OurNet::BBSAgent('cvic.bbs', undef, 'testlog');

# $cvic->{debug} = 1; # Turn on for debugging

$cvic->login($ARGV[0] || 'guest', $ARGV[1]);
print "now at $cvic->{state}";
$cvic->Hook('balloon', \&callback);
$cvic->Loop;

sub callback {
    ($caller, $message) = @_;
    print "Received: $message\n";
    exit if $message eq '!quit';
    $cvic->balloon_reply("$caller, I've got your message!");
}

DESCRIPTION

OurNet::BBSAgent provides an object-oriented interface to TCP/IP-based interactive services (e.g. BBS, IRC, ICQ and Telnet), by simulating as a "virtual user" with action defined by a script language. The developer could then use the same methods to access different services, to easily implement interactive robots, spiders, or other cross-service agents.

Site Description File

This module has its own scripting language, which looks like this in a site description file:

CVIC BBS
cvic.org:23

=login
wait µù¥U
  or ¨Ï¥ÎªÌ
send $[username]\n
doif $[password]
    wait ±K½X
    send $[password]\n\n
endo
send \n\n\n
goto main

=main
send eeeeeeee
wait ¥D¥\¯àªí
till Call¾÷

=balloon
wait \e[1;33;46m¡¹
till \e[37;45m\x20
till \x20\e[0m
exit

=balloon_reply
send \x12
wait ¦^¥h¡G
send $[message]\n
wait [Y]
send \n
wait \e[m
exit

The first two lines describes the service's title, its IP address and port number. Any number of 'procedures' then begins with =procname, which could be called like $object-procname([arguments])> in the program. Each procedure is made by any number of following directives:

wait STRING =item till STRING =item or STRING

Tells the agent to wait until STRING is sent by remote host. Might time out after $self-{timeout}> seconds. Any trailing or directives specifies an alternative string to match.

If STRING is of format m/.*/[imsx]*, it will be treated as a regular expression. This is an experimental feature and the interface is subject to change.

Additionally, till puts anything between the last wait or till and STRING into the return list.

send STRING

Sends STRING to remote host.

doif CONDITION =item else CONDITION =item endo

The usual flow control directives. Nested doif...endos is supported.

goto PROCEDURE =item call PROCEDURE

Executes another procedure in the site description file. goto never returns, while call always will. Also, a call will not occur if the destination was the last executed procedure that does not end with exit.

exit

Marks the termination of a procedure; also means this procedure is not a 'state' - that is, multiple calls to it will all be executed.

back

Event Hooks

In addition to call the procedures one-by-one, you can 'hook' those that begins with 'wait' (or 'call' and 'wait') so whenever the strings they expected are received, the responsible procedure is immediately called. You can also supply a call-back function to handle its results.

For example, the code in "SYNOPSIS" above 'hooks' a callback function to procedure 'balloon', then enters a event loop by calling Loop, which never terminates except when the agent receives '!quit' via the balloon procedure.

The internal hook table could be accessed by $obj->{hook}. It is implemented via a hash of hash of hash of lists -- Kids, don't try this at home!

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

Copyright 2001 by Autrijus Tang <autrijus@autrijus.org>.

All rights reserved. You can redistribute and/or modify this module under the same terms as Perl itself.