Calling LPC from MOO
====================

LPMOO offers the ability to call LPC functions from MOO. You may wish to
implement critical pieces of functionality in LPC, for example, if speed is
important or if it otherwise isn't possible to implement the functionality in
MOO.

A couple of example LPC objects are provided with LPMOO to demonstrate the
possibilities.

The LPC object /lpc/filesys (compiled from the file /lpc/filesys.c in LPMOO's
mudlib directory) contains several functions which allow the MOO to access the
filesystem of the mudlib.

Here are some examples:

  ;"/lpc/filesys":list("/*")
  => {"README", "doc/", "etc/", "include/", "lib/", "lpc/", "obj/", "std/",
      "tmp/", "verb/"}

  ;"/lpc/filesys":basename("/foo/bar")
  => "bar"

  ;"/lpc/filesys":file_size("/README")
  => 320

In every case, the arguments passed to the LPC function are converted from MOO
into LPC, the function is called, and the return value is converted from LPC
back into MOO.

MOO->LPC argument conversion occurs according to the following rules:

  - numbers => ints
  - strings => strings
  - objects => LPC object if valid, 0 otherwise
  - errors  => string error name
  - lists   => mixed arrays
  - floats  => floats
  - tables  => mappings
  - buffers => strings

LPC->MOO return value conversion occurs according to these rules:

  - ints     => numbers
  - strings  => string if non-binary; else buffer
  - objects  => object if a MOO object reference, else a string LPC object name
  - arrays   => lists
  - floats   => floats
  - mappings => tables

Another LPC object, /lpc/utils, contains some other example utility functions.

Since functions in any LPC object can be called with this mechanism, its use
is restricted to tasks running with wizard permissions. Care should especially
be taken when attempting to call functions in objects vital to the simulation,
and in general this should be avoided. Future versions of LPMOO may enforce a
restriction against calling such functions.

The object /std/moo is provided as a simple interface to the MOO database. To
use it, put:

    inherit "/std/moo";

at the top of your LPC file. You may then use the following functions:

mixed getprop(object obj, string name)
  - return the contents of the MOO property obj.(name) as an LPC value
  - `obj' must be a MOO object reference
  - `name' must be all lowercase
  - the property value is converted to an LPC value automatically

void setprop(object obj, string name, mixed newvalue)
  - set the MOO property obj.(name) to contain `newvalue'
  - `obj' must be a MOO object reference
  - `name' must be all lowercase
  - `newvalue' is converted to a MOO value automatically