POO Programmer's Reference

Purpose: This document is intended for to be the central repository of information needed by POO users for writing POO functions.

Status: This document is a work in progress, and rather behind schedule. But the information herein is believed to be accurate.

  1. General Remarks
  2. The POO Parser
  3. POO classes and their methods
    1. Func
    2. Property
    3. Obj
    4. User (derived from Obj)
    5. Directory (derived from Obj)
    6. CmdDef
  4. POO global functions
  5. POO special keywords & variables
  6. available standard Python services
  7. POO coding FAQ

    General Remarks

    Everything in POO is an object -- places, exits, players, etc. Each POO object is internally represented as a Python object (of class Obj or one of its descendants). However, these are specially designed objects with some properties not typical of generic Python objects:

    The POO Parser

    Whenever you are interacting with POO, you are connected to a user object. This object may be in edit mode (as when editing a function, list, or tuple), or in command mode (the more usual case). In command mode, your input is passed to the POO parser. If the line you enter begins with '%' or ';', the rest of the line is treated as plain Python code and executed as such. Otherwise, the parser attempts to match your input with some command.

    Commands are data structures defined on POO objects, indexed by the first word (usually the verb). Each command has a syntax definition and a function definition. The parser first searches your command for object references; these are anything that starts with '$' or '#', or the name or alias of an object inside the user or the user's location. The user and the user's location are added to the list of objects referenced in the command, to generate the object set. Each object on the object set is searched for commands which might match the input. When multiple matches are possible, the POO parser will match the one which appears more specific (e.g., matching "42" with an "<int>" syntax tag is considered more specific than matching it with "<str>").

    Once the most specific matching command is found, that command is invoked. Tagged parts of the input (e.g., "42" tagged as "<int>") are parsed and passed to the function, as defined in the command structure.

    (More detail on defining commands will be provided soon!)

    Class: Func

    This class implements a POO function. Objects of this class walk like functions, but they are pickleable and do permission checks.

    POO functions (sometimes called methods) are actually implemented internally as Python objects. Each function has three important properties, and two methods:

    Functions can be (indeed, must be) object properties, and are inherited just like any other properties.

    Class: Property

    This class implements a POO property. These are used instead
    of normal Python attributes to give us full access control.

    Class: Obj

    This is the base class of any POO object -- rooms, users,
    widgets, etc. It implements a 'multiple superinheritance'.

    All "nouns" (i.e., persons, places, or things) in a POO universe are derived from the Obj class. Not surprisingly, Obj is the biggest and most complex class in the POO hierarchy. The following methods are documented for the Obj class. Methods not documented here are subject to change without notice, and should not be used in POO code.

    Built-In Methods of Class Obj
    Obj.tell(*what) put the given string or list of strings in our auditory buffer. Terminate with a carriage return.
    Obj.tell_noCR(*what) put the given string or list of strings in our auditory buffer. Do not terminate with a carriage return.
    Obj.getprop(propname) return the Prop defined on this object or an ancestor with the specified name.
    Obj.canAddOrDeleteProp(propname) return 1 if permHolder can add a property to this object
    Obj.canWriteProp(propname, useCflag=1) return 1 if current permHolder can change the given property.
    Obj.setParents(parents) change parents of this object to the given object or list.
    Obj.do_cmd(cmd) attempt to execute the given POO command.
    Obj.proplist() return a list of all property names.
    Obj.isa(what) return 1 if what is an ancestor of self.
    Obj.contents() return list of objects contained by self.
    Obj.getCmdDef(verb, inherit=1 ) This method returns a (possibly empty) tuple of commands which begin with the given verb from this object's command dictionary.
    Obj.setCmdDef(verb, pattern, funcdef ) This function sets a command definition in the global dictionary. If the given function call is None or an empty string, the command will be removed. If the given pattern matches an existing one exactly, the existing one will be replaced. This function requires wiz privs.

    In addition to these built-in methods, there are some POO methods which may be invoked by the engine, when they exist. These can be defined and overridden from within POO. These methods are as follows:

    Method Hooks for Class Obj
    update(self) This method is called on an Obj if its .wantsUpdates property is true (e.g., set to 1). It is called on every "tick" of the simulation clock. Use with extreme caution, as misuse can slow the server down tremendously.
    hear(self, msg) This method, when present, is called when the Obj is told some message (via the .tell(*) or .tell_noCR(*) methods) -- in other words, whenever the Obj hears something. It can be used to make objects that respond to output. Use with extreme caution, since an infinite loop may be caused if an object responds to its own output (or if two objects respond to each other's output).
    postEdit(self, obj, propname, saved) This method is called on when a user completes an editing operation (by saving or aborting). It is passed the object on which the edited property was defined, the name of that property, and a flag that indicates whether the user saved changes.

    There are also two special methods which are only called on object #0. These methods are as follows:

    Method Hooks for Obj #0
    login(self,who) This method is called when a person (identified by who) connects to it over the network (i.e., logs in).
    logout(self,who) This method is called when a person (identified by who) disconnects (i.e., logs out).

    Class: User (derived from Obj)

    This subclass of Obj defines the class of Users in the game.
    They have all the properties of other POO objects, but also
    have facilities for being connected via the network.

    A User is a POO object that is connected to a real person via the network; in other words, the "characters" of the virtual environment.

    Built-In Methods of Class User
    User.connected() return 1 if this User is currently logged in.
    User.startEdit(object,propname,postEdit=None) invoke the editor on the named object property. If present, postEdit should be a function which will receive the object reference, property name, and a "saved" parameter which will be 0 if user aborted, 1 if user saved changes.
    User.enterFunc(object,funcname) start the editor on the given function, creating it if it does not already exist.

    Class: Directory (derived from Obj)

    This subclass of Obj defines the class of Directories in the game. These are POO objects which are only used for keeping references to other objects. They have the special characteristic that contents are treated like properties; that is, if Directory "foo" contains an object called "bar", it can be referred to as "foo.bar".

    Directories are severely restricted, so that they may be freely
    used within a quota system (i.e., they won't take up much memory).

    Class: CmdDef

    This class implements a pattern-matcher, where the pattern
    is formed of words and tags. It can compare its pattern
    to a string and if it matches, return a list of words which
    fit in for each tag.

    POO Global Functions

    The following POO-specific functions are available (in immediate mode or within a function). Functions usable only by wizards are not shown.

    destroy(obj) This function recycles the specified object. Caller must be the owner of the object, or a wizard. Whenever possible, use the @recycle command instead of calling this method directly.
    getObj(x) This returns a reference to the object specified by x. If x is an integer, it returns the object whose id==x. If x is a string that starts with "$", the rest of the string is taken as the name of a property on object 0 which refers to another object. If x is a string beginning with "#", the rest of the string is converted to an integer and used as the object id. If x=="ALL", then a list of all objects in the database is returned.
    globalkeys() This function returns the names of all global variables, functions, and datatypes. Note that the standard Python globals() function is unavailable within POO for security reasons.
    help(topic) This function returns the help database entry for the given topic.
    open(filename) A restricted version of the open function is available. It accepts only simple filenames (no relative or absolute pathnames). Ask the POO administrator what files are available for reading.
    show(message, parties, broadcast=1) This function displays an effect involving several parties. Each of the parties gets a customized message, and the first party's location gets a general message to its broadcast function (if any), unless the last parameter (broadcast) is 0.

    message: string containing key tags, e.g., "%1D %1:(gets) %2i."
    parties: dictionary mapping keys to objects, e.g., {1:caller, 2:dobj}
    broadcast: key of object whose location also gets a message

    split(str) This function splits the given string into a list of tokens, treating quoted strings as unitary tokens.
    tostr(x) Converts x into a string; deals intelligently with object, property, and function references.
    users() Returns a list of all connected users.

    Other Object Methods in the Core Database

    The methods below are not built into the POO engine; rather, they are functions that can be defined on POO objects and that have special significance in the standard core database.

    description(looker) This function is called by the $user.look method (and possibly others), to get the description of the object. The default method simply returns the contents of .desc (converting a list to a string if necessary). This may be overridden to generate descriptions which vary according to time, objects present, etc. Create this function with:
    @newfunc description(this,looker) on myobject
    hear(msg) This function is called when an object "hears" something in the room. Create this function with: @newfunc hear(this,msg) on myobject
    update() If defined on an object whose .wantsUpdates flag is set to 1, then this function is called on every update cycle. Errors are reported to the object's owner. CAUTION: use this function sparingly!

    POO special keywords & variables

    In addition to any parameters, functions can access POO global variables. An important one is gCmdLine, a string which contains the command line exactly as typed by the user. Other globals can be found with the command ;print globalkeys().

    A few special globals are defined whenever a function is invoked. These are for your information only; assigning to them has no effect. The predefined function globals are:

    Available Standard Python Services

    Certain common standard Python modules are available from within POO. These include the randint, time, and ctime functions, as well as the entire string and md5 modules.

    POO coding FAQ

    How do I...

    Last Updated: 11/09/97 . . . . . . Joe Strout