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

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