NAME

OurNet::BBSAgent - Scriptable telnet-based virtual users

SYNOPSIS

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

use OurNet::BBSAgent;

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

# $cvic->{debug} = 1; # Turn on if you want debugging

$cvic->login($ARGV[0] || 'guest', $ARGV[1]);
callback($cvic->balloon()) while 1; # procedural handling

$cvic->Hook('balloon', \&callback); # callback-based handling
$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:

    ELIXUS BBS
    elixus.org:23

    =login
    wait ¥N¸¹¡G
    send $[username]\n
    doif $[password]
	wait ±K½X¡G
	send $[password]\nn\n
    endo
    send \n\n\n\n

    =main
    send qqqqqqqq
    wait ¥D¥\¯àªí
    till ©I¥s¾¹

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

    =balloon_reply
    send \x12
    wait ¦^À³
    send $[message]\n
    wait [Y]
    send \n
    wait \e[37;45m
    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:

load FILENAME

This directive must be used before any procedures. It loads another BBS definition file under the same directory (or current directory).

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 elif CONDITION =item else =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.

setv VAR STRING

Sets a global, non-overridable variable (see below).

idle NUMBER

Sleep that much seconds.

Variable Handling

Whenever a variable in the form of $[name] is encountered as a part of a directive, it is looked up in the global 'setv' hash $self-{var}> first, then at the procedure-scoped variable hash, and is shift()'ed from the argument list if none are found.

For example:

setv foo World!

=login
send $[bar]      # sends the first argument
send $[foo]      # sends 'World!'
send $[password] # sends the second argument
send $[username] # sends the first argument again

A notable exception is digits-only subscripts (e.g. $[1]), which contains the matched string in the previous 'wait' or 'till' directive. If there are multiple strings via 'or' directives, the subscript correspond to the matched alternative. For example:

=match
wait foo
  or m/baz+/
doif $[1] # 'foo' matched
    send $[1] # sends 'foo'
else
    send $[2] # sends 'bazzzzz...'
endo

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.