Status: This document is a work in progress, and rather behind schedule. But the information herein is believed to be accurate.
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!)
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.
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). |
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. |
Directories are severely restricted, so that they may be freely
used within a quota system (i.e., they won't take up much memory).
| 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." |
| 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. |
| 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! |
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:
Alternatively, use the show function:
show( "%1D %1:(bonks) %2i on the head.", {1:user, 2:dobj} )
if type(x) != InstanceType or x.__class__ != Directory: raise "ParamError", tostr(x) + " is not a Directory"The object class might also be Obj, User, Func, or Prop.
If you know that x is an Obj (or one of its derivatives, User or Directory), and want to see whether it is descended from some other POO object, use the .isa() function. For example:
if x.isa(getObj('$exit')): print "It's an exit all right!"
stddesc = super(looker) # first, get standard descriptionNotice that you don't specify self when invoking super; super knows what object it's being invoked from. However, any other arguments which were passed to your function must be passed on to super.