NAME

MCP - MUD Client Protocol support in Perl


SYNOPSIS

    use MCP;
    $pkg = Define MCP::Package 'dns-org-mud-moo-simpleedit',
      min_version => "1.0",
      max_version => "1.0";
    define_initializer $pkg sub {
       my ($session) = @_;
       $session->write_inband("\@edit me.foo\r\n");
    };
    define_method $pkg content => sub {
       my ($session, $params) = @_;
       print "Reference: $params->{reference}\n";
       print "Name: $params->{name}\n";
       print "Type: $params->{type}\n";
       foreach (@{$params->{content}}) {
          print "$_\n";
       }
       print "\n";
       $session->write_inband("\@quit\r\n");
    };
    $|=1;
    my $socket = IO::Socket::INET
      ->new(PeerAddr => "random.moo.mud.org", PeerPort => 8888);
    $sess = MCP::Session->new($socket, client => 1);
    $sess->start_mcp();
    $sess->write_inband("connect $user $password\r\n");
    while (<$socket>) { $sess->eat_line($_); }
    $sess->close();


DESCRIPTION

MUD Client Protocol is a means for multiplexing a bidirectional stream of structured messages onto a single line-oriented channel. For more details see http://www.moo.mud.org/mcp/


MCP::Package

The following methods are available:

MCP::Package->Define(name, [attrib => value,...])
Creates a package definition. Allowed attributes include
min_version
Minimum version supported by this implementation

max_version
Maximum version supported by this implementation

pkginst
The class from which to instantiate package instances if other than MCP::PkgInst (class must still be a descendant of MCP::PkgInst).

initial
Package initializer. Supplying this is equivalent to using define_initializer below.

final
Package finalizer. Supplying this is equivalent to using define_finalizer below.

$package->name
Returns the package name.

$package->method_name($name)
Returns the fully qualified method name corresponding to $name

define_method $pkg name => sub { my($session,$params) = @_; ... };
$pkg->define_method(name => sub { my($session,$params) = @_; ... });
Defines a message handler.

define_initializer $package sub { my($session,$params) = @_; ... };
$package->define_initializer(sub { my($session,$params) = @_; ... });
Defines a package initializer. Initializers run as soon as version negotiation succeeds in a given session.

define_finalizer $package sub { my($session,$params) = @_; ... };
$package->define_finalizer(sub { my($session,$params) = @_; ... });
Defines a package finalizer.

$package->inst($session)
Returns $session's package instance object for this package, if any.


MCP::Session

The following methods are available on session objects:

MCP::Session->new($out, [param => value ...])
Constructs a new MCP::Session object atop the given output filehandle $out. The following parameters are recognized:
client => boolean
server => boolean
One of client or server should be specified A server session issues the initial #$#mcp immediately, A client session waits for the peer to issue the #$#mcp.

close => coderef
A subroutine to be called when this MCP session is terminating. It should return true according as the caller will be invoking $session->close_hook() by itself

abort => coderef
A subroutine to be called if MCP version negotiation fails

echo => boolean
echo back all received MCP message lines on output as in-band lines

serial
derive the session's id from this string instead of generating one

$session->start_mcp()
Begin MCP activity on this session, installing the root message handler and, for server sessions, sending the initial handshake message.

$session->close([$reason])
Call the close parameter supplied to new, if any, to indicate that this session is to be terminated

$session->close_hook([$reason])
Does the actual work of terminating a session, disabling all of the message handlers and invoking the various package finalizers.

$session->is_closed()
Has this session been closed?

$session->is_client()
Is this a client session rather than a server session?

$session->send_msg($full_method_name [, keyword => value ...])
Sends an out-of-band message. Scalar values are stringified. An array-reference value causes the corresponding keyword to be treated as a multiline key.

$session->write_inband($string)
Sends an in-band string. Any lines beginning with the out-of-band prefix are suitably quoted.

Complete lines are sent immediately. Any trailing partial line is saved and prefixed to the next write_inband() call.

$session->eat_line($string)
Feeds a single network line (including newline) to the session. If the line is in-band, return it, unquoted as necessary. If the line is out-of-band, parse it, dispatch it, and return false.

Expected usage is something like:

  while (<>) { $session->eat_line($_); }

$session->eat_string($string)
Feeds an arbitrary string of network characters to the session. Each complete out-of-band line is extracted, parsed, and dispatched. Quote prefixes are removed from quoted in-band lines. Remaining complete (in-band) lines are removed from $string and returned as a list (possibly empty).

Any trailing partial line is left behind in $string.

Expected usage is something like:

  while (sysread(HANDLE, $buffer, $chunk_size, length($buffer))) { 
      foreach ($session->eat_string($buffer)) {
          # ... process inband line $_;
      }
  }

receive_msg($name, [kwd => $value ...])
(debugging) Simulates receiving an out-of-band message. Values must be strings or array references (of string arrays).

new_from_fd($fd, [kwd => $value ...])
(debugging) Creates a session from an output file descriptor. Keyword paramters are as for new.


COPYRIGHT

Copyright 2002 Roger F. Crew.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.