This is docs/programmers_guide.info, produced by makeinfo version 4.6
from docs/programmers_guide.texinfo.

This manual is for MOZ (MOO in Oz) version 1.0.

   Copyright (C) 2003 Robin Lee Powell

     Permission is granted to distribute and modify as long as credit is
     given.  See the file license.txt in the main MOZ distribution for
     full copyright information.
   

File: programmers_guide.info,  Node: Top,  Next: General Issues,  Up: (dir)



This is the Programmer's Guide for MOZ (Moo in OZ). MOO is Mud Object
Oriented.  MUD is Multi-User Dungeon or Dimension.  In general, a MUD is
a multi-user text-based virtual environment.  For information on MUDs in
general, see `http://www.godlike.com/muds/' or your local search
engine.  For information on MOOs, see `http://www.moo.mud.org/moo-faq/'.

   Oz is a multi-paradigmatic language that happens to not suck.  See
`http://www.mozart-oz.org/'.

* Menu:

* General Issues::	Some basic concepts you should be aware of
			to program in MOZ.

* Class Creation::	How to create a new class, and what to
			populate it with.

* Control Objects::	Every object that is created causes the
			creation of a control object so that the
			player can do arbitrary things to the object
			they just got.  This section describes some
			details about control objects that a
			programmer needs to know.

* Verbs::		Information about verbs and how to create them.
			Note that verbs work rather differently in MOZ:
			each verb defines how its arguments should be
			parsed.

* Core Classes::	The internal classes from a progammer's point of
			view, including methods on each class.

* Unsorted::		Point-form notes that haven't been fully fleshed
			out.
* Command Index::
* Method Index::


File: programmers_guide.info,  Node: General Issues,  Next: Class Creation,  Prev: Top,  Up: Top

General Issues
**************

* Menu:

* Introduction::	A very basic overview of MOZ programming.

* Localized Strings::	About the string type MOZ uses, and how to
			generate them.


File: programmers_guide.info,  Node: Introduction,  Next: Localized Strings,  Up: General Issues

Introduction
============

***UNFINISHED***


File: programmers_guide.info,  Node: Localized Strings,  Prev: Introduction,  Up: General Issues

Localized Strings
=================

To deal with MOZ's requirement to be able to output to users in
multiple languages, a MOZ programmer should never use Oz strings for
output at all.  Instead a structure called a Localized String is used.
This is a record, with a feature for each language (using whatever
short code is defined in the Server object, such as `en' for English).
Each feature holds a string that is the string that should be output
for a user that uses that language.  An example:

     string(
         en: "A sample string.\n"
         lb: ".i le mupli seltcidu\n"
     )

   However, for output of strings from program code (as opposed to
output of strings set by players directly, such as those stored in
names and descriptions), you shouldn't enter these strings directly.
Instead, you should first add the strings to the LanguageStrings object
using the ***UNFINISHED*** command.  The `tell' method on the Player
object will treat any atom by itself as a key into the database on
LanguageStrings, making it easy to use these strings in your code.

   The reason to do this is it makes it much easier for others to
translate everything in the MOZ to a new language if everything is
collected on one object and easily retrievable.


File: programmers_guide.info,  Node: Class Creation,  Next: Control Objects,  Prev: General Issues,  Up: Top

Class Creation
**************

**UNFINISHED** Here go some notes about what classes are and why you
would want to create one.

* Menu:

* Class Creation Introduction::		An introduction to class creation
				issues.

* Creating A Class File::	How to create a class file, as well
				as how to put text into it.

* Required Attributes And Features::
				The minimal set of attributes and
				features a class must have to play
				nicely with the rest of the MOZ.
* Common Methods::		Methods that you'll likely want to
				define on any object.


File: programmers_guide.info,  Node: Class Creation Introduction,  Next: Creating A Class File,  Up: Class Creation

Class Creation Introduction
===========================

**UNFINISHED** Stuff about why you'd want to create classes (especially
since this is the fundamental thing that makes one a MOZ programmer),
stuff about class items and how to use them to control classes.


File: programmers_guide.info,  Node: Creating A Class File,  Next: Required Attributes And Features,  Prev: Class Creation Introduction,  Up: Class Creation

Creating A Class File
=====================

 - Variable: create class named `className'
     Use this command to create a class you can edit.  Actually, it
     technically only creates an object of class ClassControl, which you
     then use to write and compile the class.

 - Variable: write class `className'
     Takes text until you enter "EOF" on a line by itself, and puts that
     text in the class file.  You must have run `create class' for this
     to work.

 - Variable: compile class `className'
     Compiles a class written using `write class'.  Note that if your
     class has certain types of bugs, this will hang.  You will be able
     to continue your activity in the MOZ, though, and try again if you
     like.


File: programmers_guide.info,  Node: Required Attributes And Features,  Next: Common Methods,  Prev: Creating A Class File,  Up: Class Creation

Required Attributes And Features
================================

**UNFINISHED**

   Test.

Attributes
----------

NAME
     A localized string containing the object's name in the MOZ.

STORAGEREF
     The storageRef attribute just holds an object reference record
     for the MOZ's central Storage object.  _Every_ object in the MOZ
      needs to talk to Storage at some point.

LANGUAGESTRINGSOBJECTREF
     Holds the global set of localized strings, which all system
     object should use.

HASPROPERNAME
     A boolean declaring if the object's name is a proper name (like
     Alice or Bob) or a generic name (like couch or door or puppy).

VERBS
     A place to store the list of input verbs that this class
     recognizes.  Note that there are special methods to deal with
     this structure; it should not be touched directly.

PUBLICMETHODS
     This is a list of methods we let _everybody_ see.  In
     particular, this list is used to give basic capabilities to an
     object's location, and vice versa.

     The list is updated using ADDPUBLICMETHOD.

SERVERREF
     The serverRef attribute just holds an object reference record
     for the MOZ's central Server object.


Features
--------

OZNAME
     The ozName feature; holds an Oz name value unique to the
     current object.

EXPORTS
     The exports feature holds a list of 2-tuples detailing the
     attributes to be handled by toRecord and fromRecord.  In other
     words, it lists all attributes that need to be saved to disk to
     preserve the state of a member of this class, so it is     _very_
     important to fill exports properly.

     The 2-tuples are the name of the attribute and its type.  Most
     type atoms are ignored, but some must be specially handled (i.e.
       object references, which must be mediated by the Storage
     object).

     A minimal example:

              exports: [
                  storageRef#objectRef
                  serverRef#objectRef
                  languageStringsObjectRef#objectRef hasProperName#bool
                  name#string
              ]

     A more complicated example, with multiple inheritance:
          exports: {Append
              {Record.toListInd
                  {Adjoin
                      {List.toRecord exports Location.exports}
                      {List.toRecord exports Mobile.exports}
                  }
              }
              % Our local exports
              [ language#atom outputPort#notPersistent ]
          }

FEATEXPORTS
     featExports is just like exports, except for features instead of
      attributes.

     A minimal example:
              featExports: [ ozName#name capabilityDict#dict ]

METHODLIST
     The methodList feature just holds a list of the names of the
     methods that the wrapper should make capabilities for, i.e. the
     externally available methods.  Note that UPGRADE should     not
     be here, because it's handled specially.

     A minimal example:
              methodList: [
                  init start stop ozName className toRecord fromRecord revoke
                  hasProperName getName setName deLocalize getVerbs addVerb
              ]

     A more complicated example, with multiple inheritance:
              methodList: {Append
                  {Merge
                      {Sort Location.methodList Value.'>'}
                      {Sort Mobile.methodList Value.'>'}
                      Value.'>'
                  }
                  % Our local methods.
                  [
                      tell setLanguage getLanguage sayVerb setStorage
                      reloadVerb languagesVerb languageVerb helpVerb
                  ]
              }

CLASSNAME
     The class name, stored as an atom:

              className: 'MozBase'

CAPABILITYDICT
     The capability dictionary for this object.

WRAPPER
     The active object wrapper procedure for this object.


File: programmers_guide.info,  Node: Common Methods,  Prev: Required Attributes And Features,  Up: Class Creation

Common Methods
==============

`start'
     The start method is run everytime a new object is created, which
     includes when it is first loaded into the MOZ or upgraded, as well
     as at other times in some cases.

     The start method is normally either passed the boolean
     ISFORUPGRADE feature if the start is being run during an upgrade
     (which can require special processing) or nothing at all.

`stop'
     The stop method works like the start method in all respects except
     that it is run before the object is shut down or upgraded.



File: programmers_guide.info,  Node: Control Objects,  Next: Verbs,  Prev: Class Creation,  Up: Top

Control Objects
***************

Every object that is created causes the creation of a control object so
that the player can do arbitrary things to the object they just got.
This section describes some details about control objects that a
programmer needs to know.

   Control objects are of class Control, which is a child of class
Mobile.

* Menu:

* Control Verbs::	Control objects have their own special verb
			set.


File: programmers_guide.info,  Node: Control Verbs,  Up: Control Objects

Control Verbs
=============

Control objects don't use the normal verbs of their class, because they
need to provide functionality base on the class they are controlling.

   However, we don't want every verb available on the base object to be
available on the control object (you can't go through a control object
for an exit, for example) and more importantly, the verbs availble on
the control object _must_ not be available on the controlled object (we
don't want to let just anybody link an exit, for example).

   So, here's how you extend the control functionality of control
objects made for a class you've created.  It's actually fairly simple.

   First, create the verbs as normal, but instead of using `addVerb',
use `addControlVerb'.

   Second, and this is _very_ important, make sure that the verb
methods for control verbs are _not_ public.

   Thirdly, instead of using `self' when referring to the object being
controlled, use `@controlled'.


File: programmers_guide.info,  Node: Verbs,  Next: Core Classes,  Prev: Control Objects,  Up: Top

Verbs
*****

* Menu:

* Verb Methods::	Methods that do the actual processing for
			verb calls have a special list of default
			arguments, and return a special result
			record.

* Verb Record Structure::	A description of how verb parsing
				records are structured.

   Methods that do the processing for a verb call have special default
arguments that are sent to them, as well as needing to return a
specialized result value.


File: programmers_guide.info,  Node: Verb Methods,  Next: Verb Record Structure,  Up: Verbs

Verb Methods
============

Verb Methods Are Always Public
------------------------------

Except for the special case noted in *Note Control Verbs::, methods
used for a verb must always be publicly accessible, or they won't be
usable.  This just means adding a call like this to the `init' method
on the class:

     {self addPublicMethod( method: myVerb ) }

Verb Method Default Arguments
-----------------------------

`caller'
     The objectRef for the calling object.

`player'
     The objectRef for the player object.

`language'
     The language of the verb itself, for when the player is able to run
     verbs in multiple languages (i.e. help has language en, sidju has
     language lb).

`result'
     The result of the verb, a record that indicatats success or failure
     of the method, among other things. It is described thoroughly in
     the next section.  If the result is not set, success is assumed.

`force'
     If FORCE is set to true, no checking should be done to see if the
     current object is the one the verb call was intended for: it is
     assume that this object is, in fact, the correct choice.  Such
     checking would be things like name and alias matched, for example.


Verb Method Result Records
--------------------------

The RESULT argument gets filled with a with a record similar to the
pseudo-code one below:

     result(
         status: success|failure|other  -- default success
         certainty: float from 0.0 through 1.0 -- default 1.0
         comments: <localized string> -- default nil, only relevant to failures
     )

   There are a couple of problems that this structure is intended to
address.

   The first is that we want the option of delivering a specialized
failure message from whichever object and method knows best what the
problem was if things didn't work.  The difficulty there is that many
failure will be from objects that really are *not* the one the verb
call was intended for, so we don't want to return their errors to the
user.

   The second problem is that on object might honestly not be sure if a
verb call, that would in fact be successful, is meant for itself.  For
example, if an alias is used, or the name matches but only in a
case-insensitive fashion, those matches should introduce some doubt as
to whether the object in question is really the one the verb call was
intended for.

   The solution to these is the CERTAINTY field.  The CERTAINTY field
is a number from zero (0) to one (1), inclusive, which indicates how
certain the verb method is that it was the intended target for the
original verb call.  In the case of target uncertainty, the STATUS
should be 'other'.

   The CERTAINTY field is ignored if the STATUS is success.

   If no STATUS field was set to success out of a group of verb method
checks, the result records are sorted by CERTAINTY. The highest
non-zero value whose STATUS is *not* failure is called again with the
FORCE argument set to true.  This selects, out of the methods that
weren't sure they was being talked to, the method that was _most_ sure
it was the intended target.  Verb methods should skip all CERTAINTY
checks when FORCE is set to true.

   If there are only failures, the failure with the highest CERTAINTY
has its COMMENTS field de-localized and sent to the player to help them
figure out what happened.

   Note that non-verb methods often also have `result' arguments.  If
so, they will often not return a CERTAINTY feature as part of their
result record, because that sort of thing is the verb method's job to
determine.


File: programmers_guide.info,  Node: Verb Record Structure,  Prev: Verb Methods,  Up: Verbs

Verb Record Structure
=====================

Please note that this first section is largely not something you need
to use: the `addVerb' method allows you to avoid most of the technical
details.  The section on Parse Records, on the other hand, is quite
important.

   Verb records are used to associate particular types of user input
with methods on objects.  This means that when you type "list
languages", a verb record somewhere (on your Player object, in fact) is
used to compare against that to find out what method to call (in this
case, the 'languagesVerb' method).

   Verb records are stored in the `verbs' attribute.  The `verbs'
record has features for each language that the object has verbs on, like
so:

     verb: allVerbs(
         en: <verb records>
         lb: <verb records>
     )

   The label of the record, in this case allVerbs, is irrelevant, as are
the labels of all records in this section, unless specificially
mentioned otherwise.

   The verb records themselves contain one feature for each verb word
(that is, the first word of input) that the object wants to accept,
like so:

     en: verbs(
         help: <verb record>
         languages: <verb record>
     )

   Each actual verb record contains the language the verb was called
in(1), and the parsing structure:

     help: help(
         language: en
         parses: [
     	helpVerbParseName(
     	    method: helpVerb
     	    endOfInput: nil
     	)
         ]
     )

   The parses feature and its list are both complicated and unusual,
and are discussed in the next section.

Parse Records
-------------

The parses list is something that is very unusual for a MUD: it allows
each verb to define how its arguments are parsed, and in fact requires
that each verb do so.

   Normally, a MUD understand some basic linguistic structures of one
language, and attempts to shoe-horn whatever the player says into what
it understands.  For example, it might understand the English concepts
of subject, preposition, and object, and will attempt to understand all
input in those terms.

   MOZ, on the other hand, allows each verb in each language to define
how it wishes its input to be broken up.  It attempts to do this in a
way that requires as little programming knowledge as possible, but it's
still not exactly simple.

   The `parses' feature is, in fact, a list of records. This is used so
that one verb word can access different methods, depending on how the
rest of the line is parsed.

   _Important_: the label of the individual parse records, such as
helpVerbParseName above, _must_ be unique within the verb in question
on whatever object the parse record is being added, as addVerb uses
that label to decide what to override when you update the verb.

   The record structure for the records inside the `parses' list is as
follows: the `method' feature contains the name of the method, whatever
feature is left after that feature is removed (there should be only
one) is used as the first parsing directive.

   In this example:
     help: verb(
         language: en
         parses: [
     	playerHelpVerb(
     	    method: helpVerb
     	    endOfInput: nil
     	)
         ]
     )
   the first, and only, parsing directive is endOfInput, which sees if
the end of the user input has been reached(2).  This means that nothing,
other than whitespace, can follow the verb word "help" for this parsing
structure to match.

   On the other hand, we have:
     list: verb(
         language: en
         parses: [
             playerListLanguagesVerb(
                 method: languagesVerb
                 matchWord: matchWord(
                     word: "languages"
                     rest: rest(
                         endOfInput: nil
                     )
                 )
             )
             playerListHelpVerb(
                 method: helpVerb
                 matchWord: matchWord(
                     word: "help"
                     rest: rest(
                         endOfInput: nil
                     )
                 )
             )
         ]
     )
   which matches either the word languages, then end of input, _or_ the
word help followed by end of input.  In the two cases, different verbs
are called.

   In some cases, there will be parse records inside a parse directive;
in this case, `matchWord' has a feature, `rest', which is used to match
everything after whatever word matchWord is being used to match.  These
parse sub-records work just like the general parse records described
here, except they _cannot_ be lists, the must be single records, and
they should not include a `method' feature.

Parsing Directives
..................

Directive Name Arguments      Effect
endOfInput     nil            Matches end of character input.
string         any 1 atom     Bind the longest string (i.e. series of
                              space-seperated words) it can find to the
                              atom passed to it, which is passed to the
                              verb's method.  A word is a list of
                              anything that `Char.isGraph' returns true
                              for.  Because of this, `string' pretty
                              much always matches the entire rest of the
                              line. So, for example, "string:
                              inputString" will pass the argument
                              `inputString' to the verb's method
                              containing the rest of the line.
stringUntil    `until'        Fills `string' with words until it reaches
               `string'       a word that matches the word (or _list_ of
               `rest'         words) stored in `until'.
matchWord      `word' `rest'  The `word' argument should contain a
                              string with the word that needs to be
                              matched in the input.  `rest' contains a
                              full parse tree.
getWord        `word' `rest'  The `word' is filled with the next word in
                              the input.  `rest' contains a full parse
                              tree.
plus           `first'        This is the choice operator.  Evaluates
               `second'       `first' as a full parse tree.  If the
                              parsing of `first' succeeds, returns that.
                              Otherwise, tries to parse with `second',
                              returning that if succesful.  Otherwise
                              fails.
multiMatchWord `words'        Attempts to match anything from the list
               `wordFound'    of strings in `words'.  Whichever word is
               `rest'         actually matched is given to the method in
                              the atom named by `wordFound'.  `rest' is
                              the parse tree for everything after that
                              word.
article        `wordFound'    Same as multiMatchWord with `words' set to
               `rest'         the contents of the `articles' attribute
                              on the Parser object.
mayHaveArticle `wordFound'    Same as article, but accepts strings that
               `rest'         _don't_ start with an article as well.
bracket        `left'         Matches anything entirely inside the
               `right' `rest' brackets defined by `left' and `right'.
                              Works if both `left' and `right' are words
                              or if both are single characters, but not
                              for a mix of the two.  Note that it does
                              not deal with nesting in any real way, and
                              will only succeed if the first word or
                              character in that part of the parse
                              matches `left' and the last matches
                              `right', regardless of what's in the
                              middle.

   ---------- Footnotes ----------

   (1) Yes, this is redundant, but there are parts of the internal code
that only get to see the verb record, not the entire `verbs' structure

   (2) this is equivalent to the end of the line entered by the user at
this time


File: programmers_guide.info,  Node: Core Classes,  Next: Unsorted,  Prev: Verbs,  Up: Top

Core Classes
************

* Menu:


* Core Methods::	Information about the methods on the various
			major classes.


File: programmers_guide.info,  Node: Core Methods,  Up: Core Classes

Core Methods
============

This is a list of methods on the core classes, for use in your programs.
If it's not listed here, that's probably because the documentation is
out of date, not for security reasons or anything; MOZ is a
capablitiy-based system, if you want to shoot yourself in the foot,
that's fine.  Please inform the author of all missing entries.

   Note that this is a _very_ brief treatment of the various methods;
details should be gleaned from the source code.

   Note further that verb methods are not listed here, because they
cannot be called directly, and they can be deduced from the list of
commands anyways.

* Menu:

* MozBase Methods::
* Storage Methods::
* Server Methods::
* Connection Methods::
* LanguageStrings Methods::
* Parser Methods::
* Described Methods::
* Located Methods::
* Mobile Methods::
* Location Methods::
* Container Methods::
* Player Methods::
* Exit Methods::
* Gate Methods::
* Terminus Methods::
* Control Methods::
* ClassControl Methods::


File: programmers_guide.info,  Node: MozBase Methods,  Next: Storage Methods,  Up: Core Methods

MozBase Methods
---------------

 - Method on MozBase: init ozName storageRef serverRef
          languageStringsObjectRef
     Initializes the attributes STORAGEREF, SERVERREF and
     LANGUAGESTRINGSOBJECTREF and the feature OZNAME to the values
     passed.

 - Method on MozBase: start
     None Does nothing; here to be over-ridden in other classes.

 - Method on MozBase: stop
     None Does nothing; here to be over-ridden in other classes.

 - Method on MozBase: ozName ozName
     Returns the Oz Name associated with the current object in the
     passed variable.  Would normally be named getOzName, but this
     method is used very frequently, and the value can't be changed so
     there would be no corresponding setOzName anyways.

 - Method on MozBase: className className
     Returns the Oz Name associated with the current object in the
     passed variable.  Would normally be named getClassName, but this
     method is used very frequently, and the value shouldn't be changed
     so there would be no corresponding setClassName anyways.

 - Method on MozBase: toRecord record
     toRecord is a very important method that runs through the elements
     of the exports feature and constructs a record using the
     information therein.  This record can be pickled, saved to disk,
     and later loaded in with fromRecord.

 - Method on MozBase: fromRecord record convert objectRef
     fromRecord is the inverse operation to toRecord.  It takes the
     output of toRecord and sets attributes appropriately.  Note that
     this is a pure procedure: it is only called for its side effects.
     CONVERT is the procedure to convert stored attributes of type
     OBJECTREF into something useful, gotten from the STORAGE object.
     OBJECTREF is used to return an object reference to the newly
     initialized object, with all capabilities.

 - Method on MozBase: revoke method capability newCapability
     Revokes the current capability on the given method, assuming that
     the argument CAPABILITY matches it.  The new capability on that
     method is returned in NEWCAPABILITY.

 - Method on MozBase: hasProperName hasProperName
     Returns a boolean declaring if the object's name is a proper name
     (like Alice or Bob) or a generic name (like couch or door or
     puppy).

 - Method on MozBase: setHasProperName hasProperName
     Sets the `hasProperName' to true or false.

 - Method on MozBase: addVerb language verb parse
     Adds a verb to the objects verbs record, dealing with things like
     over-writing the same verb parse, dealing with multiple parses of
     the same verb, and the fact that the whole verb record system is
     very baroque.
    LANGUAGE
          The language the verb applies in.

    VERB
          The verb word itself ("help", "look", whatever).

    PARSE
          The parse record to add.  Note that this record will over-ride
             any other parse record for the same verb with the same
          label, so     it's important that it be reasonably unique.

 - Method on MozBase: getName name
     Standard variable get.

 - Method on MozBase: getArticledName name
     Returns the object's name with the appropriate article in front of
     it.

 - Method on MozBase: getArticledStarterName name
     Like getArticledName, but adjusts for the article being the first
     word of a sentence if a language requires that.

 - Method on MozBase: setName name
     Standard variable set.

 - Method on MozBase: getVerbs verbs
     Standard variable get.

 - Method on MozBase: deLocalize inputString outputString language
     Returns a bare string from a localized string, based on a language
     argument.

     Arguments:
    INPUTSTRING
          The string to be de-localized, in string( lang: <string> )
          format as usual.

    OUTPUTSTRING
          A normal Oz string.

    LANGUAGE
          Optional, the language to de-localize into.


 - Method on MozBase: selfMatch string certainty language
     The object returns a certainty, as a value from 0 to 1, that it is
     the object being referred to by the string in question.  The string
     should be localized.

     Possible Certainty Values:
    1.0
          A perfect string match, including case.

    0.9
          Matches only after converting both strings to lower case
          (i.e. a     caseless match).



 - Method on MozBase: addPublicMethod method
     Adds the given atom to the list of public methods for this object
     (i.e. methods for which capabilities are given out freely).

 - Method on MozBase: enhanceStorage storageRef
     Adds the capabilities on the given STORAGEREF to the object's
     current capability set for the Storage object.

 - Method on MozBase: selfReference selfRef
     Returns a complete reference for the current object, including all
     capabilities.  _Very insecure!_

 - Method on MozBase: publicSelfReference selfRef
     Returns a complete reference for the current object, with
     capabilities for only the methods in publicMethods.

 - Method on MozBase: printedList stringList string
     Takes the list of strings in `stringList' and concatenates them
     together as might be expected in a natural language string (i.e. in
     English, using commas and "and").

 - Method on MozBase: printedObjectList objectList string
     Like printedList, but the list is a list of object references, from
     which names are extracted.


File: programmers_guide.info,  Node: Storage Methods,  Next: Server Methods,  Prev: MozBase Methods,  Up: Core Methods

Storage Methods
---------------

 - Method on Storage: start args modules serverObjFileNum realStart
          newMoz
     Extracts command line arguments from ARGS, sets up links to
     external Oz modules, and if SERVEROBJFILENUM is passed, set the
     internal file number where the Server object is known to reside to
     that number.  This only happens when the MOZ is being
     re-initialized.

     NEWMOZ is used to tell the method that this is the initialization
     of a completely new moz.

 - Method on Storage: sync None
     Syncs all MOZ objects to disk.

 - Method on Storage: stop None
     Saves all MOZ objects to disk.

 - Method on Storage: info None
     Outputs debugging information; currently all commented out.

 - Method on Storage: init ozName fileNumToOzName storageRef
          languageStringsObjectRef
     Initializes a new Storage object, mostly using MozBase,init.
     FILENUMTOOZNAME is a dictionary that normally only contains a
     mapping from the number 1 to the new Storage object's Oz name.
     Initializes some other dictionaries.

 - Method on Storage: loadClasses None
     Compiles and loads all the MOZ's .class files.

 - Method on Storage: loadObject fileNum objectRef init
     This method loads an object from the disk by its number (using the
     fileNumToOzName dictionary).  It returns the object record in
     OBJECTREF.

 - Method on Storage: saveObject objectWrapper ozName
     This method saves the object information to disk.  Note that
     OBJECTWRAPPER is just the Active Object wrapper, _not_ the
     standard object reference object.

 - Method on Storage: createObject className objectRef ozName init
     Creates an object, returning a standard object reference in
     OBJECTREF.

 - Method on Storage: getClass className class
     Returns the class code for the given CLASSNAME

 - Method on Storage: upgradeObject objectRef className newObjectRef
     Upgrades the given object to the given class, returning
     NEWOBJECTREF.  Note that this could be the same class name as
     before, but the class itself has been re-loaded in the mean time.
     In fact, that should be the most common type of upgrade.

 - Method on Storage: getObjectFileNum objectRef fileNum
     Take an object reference record and returns the file number
     associated with that object reference.  Not for general use!

 - Method on Storage: getServerObjFileNum serverObjFileNum
     Returns the file number for the Server object.  Not for general
     use!

 - Method on Storage: setServerObjFileNum serverObjFileNum
     Sets the file number for the Server object.  Not for general use!

 - Method on Storage: getObjectFromFileNum fileNum objectRef
     Retrieves an object given the file number it is stored in.  Not for
     general use!

 - Method on Storage: objectRefFromRecord convert
     This is the procedure that fromRecord needs to instantiate attrs of
     type 'object'.  Full details are in the source.

     This is so far from being for general use that it's not even funny.

 - Method on Storage: logLevel level
     Set the current logging level to LEVEL.  Logging levels are, in
     order from most to least verbose, DEBUG, INFO, WARN, ERROR, and
     CRITICAL.

     The default is warn.  For whatever level is selected, that level of
     log message and above (above meaning "less verbose" or "more
     severe") are printed.

 - Method on Storage: getConnectionModule module
     Returns a copy of the Connection module.  That's the Oz Connection
     module, _NOT_ the MOZ Connection _class_.  Used by the Gate and
     Terminus classes.

 - Method on Storage: getPickleResult url pickleResult
     Treats `url' as the URL to a file containing an Oz pickle, and
     returns the result of attempting to un-pickle that file.  Used by
     the Gate class.

 - Method on Storage: writePickleToFile file value
     Writes the given value, as an Oz pickle, to the file given.  The
     file is stripped of "/" and "\" characters, and placed under the
     "pickle" directory under the server's root directory.

 - Method on Storage: getCapabilitiesFromOzName ozName capabilities
     Returns a full set of capabilities for the object associated with
     the OZNAME given.

 - Method on Storage: getObjectFromOzName ozName objectRef
     Returns an object refrence, including a full set of capabilities,
     for the object associated with the OZNAME given.

 - Method on Storage: getObjectFromFileNum fileNum objectRef
     Returns an object refrence, including a full set of capabilities,
     for the object associated with the file number given.  Please don't
     use this.

 - Method on Storage: upgradeObject objectRef className
     Forces an upgrade of the object in question.

 - Method on Storage: upgradeAll done
     Upgrades *all* objects in the MOZ.  Well, OK, all the ones Storage
     knows about (which is everything but special user-created stuff,
     for which you're on your own).

 - Method on Storage: createClass className controlRef result
     Creates a ClassControl object for the given `className', after
     checking that no such class already exists, and returns a reference
     to the new object in `controlRef'.

 - Method on Storage: writeClassFile className string result
     Writes the class file associated with the given `className' using
     the `string' given as the _entire_ text of the class file.

 - Method on Storage: loadClass className
     Recompiles the class named `className'.  Not that the actual
     compilation is threaded off.


File: programmers_guide.info,  Node: Server Methods,  Next: Connection Methods,  Prev: Storage Methods,  Up: Core Methods

Server Methods
--------------

 - Method on Server: init ozName storageRef languageStringsObjectRef
          storageObjectRef startRoom
     As per usual, except for STORAGEOBJECTREF, which passes extra,
     better capabilities to the Server object, and STARTROOM, which
     passes and object reference to the player starting room.

 - Method on Server: start args modules hold REALSTART
     As with Storage, except HOLD, which returns a variable that
     remains unbound until the server is shut down.

     REALSTART is used to say that this is the real start call, rather
     then the normal one that happens when the object is created.

 - Method on Server: stop
     Stops the server; also binds HOLD from the `start' method.

 - Method on Server: handleLogin acceptObject playerRef outputPort
          acceptProc
     Deals with a user's attempt to log in, including creating new
     player objects if necessary.  More details in the source.

 - Method on Server: upgradeStorage newClass convert
     Storage calls this to get the server to upgrade it during an
     UPGRADEALL call.  No user servicable parts inside.

 - Method on Server: changePassword player oldPassword newPassword
     If the stored password for the login name PLAYER matches
     OLDPASSWORD, changes it to NEWPASSWORD.


File: programmers_guide.info,  Node: Connection Methods,  Next: LanguageStrings Methods,  Prev: Server Methods,  Up: Core Methods

Connection Methods
------------------

 - Method on Connection: start socket storageRef modules parser
          outputStream
     Handles the connection, reading from the TCP/IP port and passing
     to the parser, and then back.


File: programmers_guide.info,  Node: LanguageStrings Methods,  Next: Parser Methods,  Prev: Connection Methods,  Up: Core Methods

LanguageStrings Methods
-----------------------

 - Method on LanguageStrings: init ozName storageRef
     Nothing unusual here.

 - Method on LanguageStrings: getLanguageString key string
     Simple dictionary lookup on the LANGUAGESTRINGS dictionary.  If
     the KEY passed as an argument does not exist, a blank, globally
     localized string is returned.  )"

 - Method on LanguageStrings: setLanguageString key string
     Dictionary write on the LANGUAGESTRINGS dictionary.  Any languages
     not covered by the STRING argument are left as they were.

 - Method on LanguageStrings: resetLanguageStrings
     Reloads all of the default language strings.  Note that if new
     languages have been added, they will not be overwritten; only the
     languages that ship with the server by default will be, and only in
     the original strings; no newly added strings will be affected.


File: programmers_guide.info,  Node: Parser Methods,  Next: Described Methods,  Prev: LanguageStrings Methods,  Up: Core Methods

Parser Methods
--------------

 - Method on Parser: start storageRef modules outputPort serverStop
          player languageStringsObjectRef
     Starts a new parser objcet.  OUTPUTPORT is the Socket object that
     is used for sending output to the player.  PLAYER is an object
     reference to the player object.

 - Method on Parser: parseOutVerb string result
     Just extracts the first word from the input string, which is then
     treated as the verb word.

 - Method on Parser: parse input
     First tests to see if the first character, by itself, is a verb,
     using matchVerbs, then tries the whole first word, again using
     matchVerbs.  If that fails, complains to the character.

 - Method on Parser: runVerb verb rest result
     Attempts to match the input verb against any verb it can get its
     hands on, starting with the player object, then the player's
     contents, then the player's room, then everybody in the room.

     This method does _not_ implement the verb record parsing strategy;
     it calls verbParseRest for that.

     VERB contains the verb word, REST contains the rest of the input,
     and MATCHED is set to true if a match was found.

 - Method on Parser: verbParseRest verbParse rest verbMethod language
          result
     Implements parsing of verb records.  Takes the parse segment of a
     verb record, and returns a record named after the verb word with
     the various arg1:, arg2: ... elements in it, filled according to
     the parse record.

    VERBPARSE
          The parse record for the verb.

    LANGUAGE
          The language of the verb match we're working against.

    RESULT
          The results of the parse, as a record named after the verb
          word with features named according to the parse record.

 - Method on Parser: eval input
     Evaluates the input as a piece of Oz code.  (1)

   ---------- Footnotes ----------

   (1) Currently isn't implemented as a verb; this needs to be fixed.


File: programmers_guide.info,  Node: Described Methods,  Next: Located Methods,  Prev: Parser Methods,  Up: Core Methods

Described Methods
-----------------

 - Method on Described: init ozName storageRef name description
     Adds name and description attributes to the standard init.

 - Method on Described: getDescription description
     Standard variable get.

 - Method on Described: setDescription description
     Standard variable set.

 - Method on Described: deLocalize inputString outputString language
     Returns a bare string from a localized string, based on a language
     argument, using the MozBase version of the same methed but passing
     a value for the Server class.  The Server information allows using
     the Server's default language value as a fallback.


File: programmers_guide.info,  Node: Located Methods,  Next: Mobile Methods,  Prev: Described Methods,  Up: Core Methods

Located Methods
---------------

 - Method on Located: init location
     Adds location to Described's list.

 - Method on Located: getLocation location
     Standard variable get.


File: programmers_guide.info,  Node: Mobile Methods,  Next: Location Methods,  Prev: Located Methods,  Up: Core Methods

Mobile Methods
--------------

 - Method on Mobile: setLocation location
     Standard variable set.


File: programmers_guide.info,  Node: Location Methods,  Next: Container Methods,  Prev: Mobile Methods,  Up: Core Methods

Location Methods
----------------

 - Method on Location: init contents
     Adds contents information to Described's list.

 - Method on Location: addToContents objectRef
     Adds the given object to the current CONTENTS list.

 - Method on Location: getContents contents
     Standard variable get.

 - Method on Location: getContentsString string
     Returns a string that contains a list of the names of all the
     objects in the object's CONTENTS list.

 - Method on Location: removeFromContents objectRef
     Removes the given object from the current CONTENTS list.

 - Method on Location: wantToGet newLocation origRecord newRecord
     This is called by other objects who desire to get one of the
     objects from our CONTENTS list.  *Note GET on Location:
     location-get.  ORIGRECORD is a minimal object reference to the
     object that NEWLOCATION wants.

 - Method on Location: wantToGive oldLocation objectRef result
     This is called by other objects who desire to give us one of the
     objects from their CONTENTS list.  *Note GIVE on Location:
     location-give.  RESULT is set to true if we accept the object,
     false otherwise.

 - Method on Location: searchByObjectName name except objectRef result
          language
     Returns the object in our contents best matching the given name,
     else returns a standard result in `result'.  `except' is used to
     exclude the calling object from the searching, as this will cause a
     hang.

 - Method on Location: announce string except
     This is called by other objects who desire to have a string
     presented to the tell methods of all objects in this location (at
     least, those _with_ tell methods).

     The `except' argument takes an object reference and causes the
     string to _not_ be presented to that object.  This is very
     important, because if you call announce and the object making the
     announce call has a tell method, the announce will hand trying to
     re-enter that object.  So, always put the object calling announce
     in the `except' argument!

 - Method on Location: get fromLocation objectRef
     Gets an object from another object, which must be a descendant of
     location.

     First we call getFrom on the from location, then put the object
     that that call returns into our contents list.

     Note that OBJECTREF is limited reference to the object we want to
     _get_.

     *Note WANTTOGET on Location: location-wantToGet.

 - Method on Location: give toLocation objectRef
     Gives an object to another object, which must be a descendant of
     location.

     First we call wantToGive on the from location, then remove the
     object that we give to that call from our contents list if the
     call returns true.  *Note WANTTOGIVE on Location:
     location-wantToGive.


File: programmers_guide.info,  Node: Container Methods,  Next: Player Methods,  Prev: Location Methods,  Up: Core Methods

Container Methods
-----------------

 - Method on Container: init
     Merges the INITs of Location and Thing; Location's INIT is run
     first.


File: programmers_guide.info,  Node: Player Methods,  Next: Exit Methods,  Prev: Container Methods,  Up: Core Methods

Player Methods
--------------

 - Method on Player: init
     Runs the INIT methods for Location and Mobile (in that order).
     Sets LANGUAGE and OUTPUTPORT to nil.

 - Method on Player: start modules outputPort realStart
     Sets the OUTPUTPORT object variable.

     REALSTART is used to say that this is the real start call, rather
     then the normal one that happens when the object is created.

 - Method on Player: stop
     Nothing special here, except during upgrades.

 - Method on Player: setStorage storage
     Just used to set the storage attribute with a new capability set.
     Used for wizardry and dewizardry and the like.

 - Method on Player: tell string language
     Sends a string to the user.  The string can either be a single
     string or a list of strings.  Any individual string can be either a
     localized MOZ string or a single atom.  If it is an atom, that atom
     is looked up on the LanguageStrings object and the result is
     output.

 - Method on Player: setLanguage language
     Standard variable set.

 - Method on Player: getLanguage language
     Standard variable get.

 - Method on Player: setStorage storageRef
     Standard variable set, for storageRef.

 - Method on Player: grabInputUntil untilString inputString result
     Takes all input entered by the player until the player types the
     string passed in `untilString'.  The input is returned in
     `inputString'.  `result' is as per usual.

     This method can only be called once every thirty seconds, to
     prevent malicious code from not letting the player interact with
     the rest of the MOZ.  Further attempts to call this method will
     return a failure result instantly.


File: programmers_guide.info,  Node: Exit Methods,  Next: Gate Methods,  Prev: Player Methods,  Up: Core Methods

Exit Methods
------------

 - Method on Exit: setDestination destination
     Sets the destination for this exit to the object given.

 - Method on Exit: setName name
     Sets the exit's name.  Also creates verbs corresponding to the new
     name, so the player can use the exit.


File: programmers_guide.info,  Node: Gate Methods,  Next: Terminus Methods,  Prev: Exit Methods,  Up: Core Methods

Gate Methods
------------

 - Method on Gate: setDestination destination
     Sets the destination for this exit to the object referenced by the
     pickle stored at given url.


File: programmers_guide.info,  Node: Terminus Methods,  Next: Control Methods,  Prev: Gate Methods,  Up: Core Methods

Terminus Methods
----------------

 - Method on Terminus: getTicket ticket
     Uses the Connection module to return a ticket to itself.

 - Method on Terminus: writeTicket file
     Uses the `writePickleToFile' method on Storage to write a ticket
     for a reference to itself to the file given (which will be
     physically stored in the "pickle" directory under the server root
     directory).


File: programmers_guide.info,  Node: Control Methods,  Next: ClassControl Methods,  Prev: Terminus Methods,  Up: Core Methods

Control Methods
---------------

 - Method on Control: getName name
     Generates a name based on the name of the underlying controlled
     object.  For example, if the controlled object is named "Dead
     Parrot", this method will return "Control Rod For a Dead Parrot".
     Also updates the Control object's `name' attribute.

 - Method on Control: selfMatch
     Makes sure that its name is set properly, based on the current name
     of the controlled object, then runs the normal `selfMatch' method.

 - Method on Control: otherwise
     The `otherwise' method is priviledged in Oz: it is called for any
     method call that doesn't match anything else.  It is used here to
     handle the extensibility of Control verbs and methods based on the
     underlying controlled object's class.

 - Method on Control: getMethodList methodList
     Returns the combined methods of the Control object and the
     controlled object.

 - Method on Control: getVerbs verbs
     Returns getControlVerbs on the underlying object.

 - Method on Control: start
     Generates a perfect object reference on the controlled object (i.e.
     one that can never lose capabilities) using a special capability
     set from Storage, and sets its `name'.

 - Method on Control: publicSelfReference
     Calls selfReference: with Control objects, possession is ten tenths
     of the law.


File: programmers_guide.info,  Node: ClassControl Methods,  Prev: Control Methods,  Up: Core Methods

ClassControl Methods
--------------------

 - Method on ControlClass: getName name
     Generates a name based on the name of the underlying controlled
     class. Also updates the Control object's `name' attribute.

 - Method on ControlClass: selfMatch
     Makes sure that its name is set properly, based on the current name
     of the controlled object, then runs the normal `selfMatch' method.


File: programmers_guide.info,  Node: Unsorted,  Next: Command Index,  Prev: Core Classes,  Up: Top

Unsorted
********

   * Provided imformation on how to upgrade a class of objects,
     including the case where there are new init() attributes on the new
     class, thus requiring an upgrade then a seperate set-method call
     of some kind, probably to a temporary set-method.

   * Add objectName or whatever to the verb record info.

   * Example verb creation, including the method.

   * Examples of 'fun' objects (meep, wind-up ducky, tame falcon).

   * Some documentation on Parsing.oz, or a pointer to it

   * Put a list of articles somewhere.

   * Document the standard arguments to verb methods.

   * Note somewhere that an init method should always be able to accept
     nothing but "ozName" and "storageRef", because upgrades will pass
     only those (and fill them with nil, expecting fromRecord to fix
     them).

   * Write out how to format a Result field in a verb method.

   * Describe all the different export and featExport types (or,
     rather, copy this info from the design doc).



File: programmers_guide.info,  Node: Command Index,  Next: Method Index,  Prev: Unsorted,  Up: Top

Command Index
*************

* Menu:

* compile class:                         Creating A Class File.
* create class:                          Creating A Class File.
* write class:                           Creating A Class File.


File: programmers_guide.info,  Node: Method Index,  Prev: Command Index,  Up: Top

Method Index
************

* Menu:

* addPublicMethod on MozBase:            MozBase Methods.
* addToContents on Location:             Location Methods.
* addVerb on MozBase:                    MozBase Methods.
* announce on Location:                  Location Methods.
* changePassword on Server:              Server Methods.
* className on MozBase:                  MozBase Methods.
* createClass on Storage:                Storage Methods.
* createObject on Storage:               Storage Methods.
* deLocalize on Described:               Described Methods.
* deLocalize on MozBase:                 MozBase Methods.
* enhanceStorage on MozBase:             MozBase Methods.
* eval on Parser:                        Parser Methods.
* fromRecord on MozBase:                 MozBase Methods.
* get on Location:                       Location Methods.
* getArticledName on MozBase:            MozBase Methods.
* getArticledStarterName on MozBase:     MozBase Methods.
* getCapabilitiesFromOzName on Storage:  Storage Methods.
* getClass on Storage:                   Storage Methods.
* getConnectionModule on Storage:        Storage Methods.
* getContents on Location:               Location Methods.
* getContentsString on Location:         Location Methods.
* getDescription on Described:           Described Methods.
* getLanguage on Player:                 Player Methods.
* getLanguageString on LanguageStrings:  LanguageStrings Methods.
* getLocation on Located:                Located Methods.
* getMethodList on Control:              Control Methods.
* getName on Control:                    Control Methods.
* getName on ControlClass:               ClassControl Methods.
* getName on MozBase:                    MozBase Methods.
* getObjectFileNum on Storage:           Storage Methods.
* getObjectFromFileNum on Storage:       Storage Methods.
* getObjectFromOzName on Storage:        Storage Methods.
* getPickleResult on Storage:            Storage Methods.
* getServerObjFileNum on Storage:        Storage Methods.
* getTicket on Terminus:                 Terminus Methods.
* getVerbs on Control:                   Control Methods.
* getVerbs on MozBase:                   MozBase Methods.
* give on Location:                      Location Methods.
* grabInputUntil on Player:              Player Methods.
* handleLogin on Server:                 Server Methods.
* hasProperName on MozBase:              MozBase Methods.
* info on Storage:                       Storage Methods.
* init on Container:                     Container Methods.
* init on Described:                     Described Methods.
* init on LanguageStrings:               LanguageStrings Methods.
* init on Located:                       Located Methods.
* init on Location:                      Location Methods.
* init on MozBase:                       MozBase Methods.
* init on Player:                        Player Methods.
* init on Server:                        Server Methods.
* init on Storage:                       Storage Methods.
* loadClass on Storage:                  Storage Methods.
* loadClasses on Storage:                Storage Methods.
* loadObject on Storage:                 Storage Methods.
* logLevel on Storage:                   Storage Methods.
* objectRefFromRecord on Storage:        Storage Methods.
* otherwise on Control:                  Control Methods.
* ozName on MozBase:                     MozBase Methods.
* parse on Parser:                       Parser Methods.
* parseOutVerb on Parser:                Parser Methods.
* printedList on MozBase:                MozBase Methods.
* printedObjectList on MozBase:          MozBase Methods.
* publicSelfReference on Control:        Control Methods.
* publicSelfReference on MozBase:        MozBase Methods.
* removeFromContents on Location:        Location Methods.
* resetLanguageStrings on LanguageStrings: LanguageStrings Methods.
* revoke on MozBase:                     MozBase Methods.
* runVerb on Parser:                     Parser Methods.
* saveObject on Storage:                 Storage Methods.
* searchByObjectName on Location:        Location Methods.
* selfMatch on Control:                  Control Methods.
* selfMatch on ControlClass:             ClassControl Methods.
* selfMatch on MozBase:                  MozBase Methods.
* selfReference on MozBase:              MozBase Methods.
* setDescription on Described:           Described Methods.
* setDestination on Exit:                Exit Methods.
* setDestination on Gate:                Gate Methods.
* setHasProperName on MozBase:           MozBase Methods.
* setLanguage on Player:                 Player Methods.
* setLanguageString on LanguageStrings:  LanguageStrings Methods.
* setLocation on Mobile:                 Mobile Methods.
* setName on Exit:                       Exit Methods.
* setName on MozBase:                    MozBase Methods.
* setServerObjFileNum on Storage:        Storage Methods.
* setStorage on Player:                  Player Methods.
* start on Connection:                   Connection Methods.
* start on Control:                      Control Methods.
* start on MozBase:                      MozBase Methods.
* start on Parser:                       Parser Methods.
* start on Player:                       Player Methods.
* start on Server:                       Server Methods.
* start on Storage:                      Storage Methods.
* stop on MozBase:                       MozBase Methods.
* stop on Player:                        Player Methods.
* stop on Server:                        Server Methods.
* stop on Storage:                       Storage Methods.
* sync on Storage:                       Storage Methods.
* tell on Player:                        Player Methods.
* toRecord on MozBase:                   MozBase Methods.
* upgradeAll on Storage:                 Storage Methods.
* upgradeObject on Storage:              Storage Methods.
* upgradeStorage on Server:              Server Methods.
* verbParseRest on Parser:               Parser Methods.
* wantToGet on Location:                 Location Methods.
* wantToGive on Location:                Location Methods.
* writeClassFile on Storage:             Storage Methods.
* writePickleToFile on Storage:          Storage Methods.
* writeTicket on Terminus:               Terminus Methods.



Tag Table:
Node: Top378
Node: General Issues1744
Node: Introduction2028
Node: Localized Strings2173
Node: Class Creation3525
Node: Class Creation Introduction4181
Node: Creating A Class File4564
Node: Required Attributes And Features5463
Node: Common Methods9522
Node: Control Objects10198
Node: Control Verbs10723
Node: Verbs11760
Node: Verb Methods12292
Node: Verb Record Structure15953
Ref: Verb Record Structure-Footnote-124109
Ref: Verb Record Structure-Footnote-224253
Node: Core Classes24336
Node: Core Methods24548
Node: MozBase Methods25618
Node: Storage Methods31164
Node: Server Methods36856
Node: Connection Methods38289
Node: LanguageStrings Methods38654
Node: Parser Methods39681
Ref: Parser Methods-Footnote-141727
Node: Described Methods41798
Node: Located Methods42590
Node: Mobile Methods42896
Node: Location Methods43121
Ref: location-wantToGet43824
Ref: location-wantToGive44122
Ref: location-get45325
Ref: location-give45723
Node: Container Methods46076
Node: Player Methods46348
Node: Exit Methods48176
Node: Gate Methods48575
Node: Terminus Methods48872
Node: Control Methods49394
Node: ClassControl Methods50902
Node: Unsorted51406
Node: Command Index52526
Node: Method Index52859

End Tag Table
