\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename programmers_guide.info
@settitle Programmer's Guide to MOZ (Moo in OZ).
@c @setchapternewpage on -- deprecated?
@c %**end of header

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

Copyright @copyright{} 2003 Robin Lee Powell

@quotation
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.
@end quotation
@end copying



@titlepage
@title Programmer's Guide to MOZ (Moo in OZ).
@author Robin Lee Powell

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@contents
@end ifnothtml

@node 	  Top
@comment  node-name, 	next,      		previous,	up
@top

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 @uref{http://www.godlike.com/muds/} or your local search
engine.  For information on MOOs, see
@uref{http://www.moo.mud.org/moo-faq/}.

Oz is a multi-paradigmatic language that happens to not suck.  See
@uref{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::
@end menu

@node General Issues
@chapter General Issues

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

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

@node Introduction
@section Introduction

***UNFINISHED***

@node Localized Strings
@section 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
@code{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:

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

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 @code{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.

@node Class Creation
@chapter 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.
@end menu

@node Class Creation Introduction
@section 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.

@node Creating A Class File
@section Creating A Class File

@defvar {create class} named @code{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.
@end defvar

@defvar {write class} @code{className}
Takes text until you enter "EOF" on a line by itself, and puts that
text in the class file.  You must have run @code{create class} for
this to work.
@end defvar

@defvar {compile class} @code{className}
Compiles a class written using @code{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.
@end defvar

@node Required Attributes And Features
@section Required Attributes And Features

**UNFINISHED**

Test.

@subsection Attributes

@table @var
@item name
    A localized string containing the object's name in the MOZ.

@item 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.

@item languageStringsObjectRef
    Holds the global set of localized strings, which all system
    object should use.

@item 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).

@item 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.

@item publicMethods
    This is a list of methods we let @emph{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 @var{addPublicMethod}. 

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

@end table

@subsection Features

@table @var
@item ozName
    The ozName feature; holds an Oz name value unique to the
    current object.

@item 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
    @emph{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:

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

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


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

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

@item 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 @var{upgrade} should
    not be here, because it's handled specially.

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

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

@item className
    The class name, stored as an atom:

@example
    className: 'MozBase'
@end example

@item capabilityDict
    The capability dictionary for this object.

@item wrapper
    The active object wrapper procedure for this object.
@end table


@node Common Methods
@section Common Methods

@table @code

@item 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
@var{isForUpgrade} feature if the start is being run during an
upgrade (which can require special processing) or nothing at all.

@item 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.

@end table





@node Control Objects
@chapter 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.
@end menu

@node Control Verbs
@section 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 @emph{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
@code{addVerb}, use @code{addControlVerb}.

Second, and this is @emph{very} important, make sure that the verb
methods for control verbs are @emph{not} public.

Thirdly, instead of using @code{self} when referring to the object
being controlled, use @code{@@controlled}.

@node Verbs
@chapter 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.
@end menu

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.

@node Verb Methods
@section Verb Methods

@subsection Verb Methods Are Always Public

Except for the special case noted in @xref{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 @code{init}
method on the class:

@example
@{self addPublicMethod( method: myVerb ) @}
@end example

@subsection Verb Method Default Arguments

@table @code
@item caller
The objectRef for the calling object.

@item player
The objectRef for the player object.

@item 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).

@item 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.

@item force
If @var{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.

@end table

@subsection Verb Method Result Records

The @var{result} argument gets filled with a with a record similar
to the pseudo-code one below:

@example
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
)
@end example

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 @var{certainty} field.  The
@var{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 @var{status} should be 'other'.

The @var{certainty} field is ignored if the @var{status} is success.  

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

If there are only failures, the failure with the highest
@var{certainty} has its @var{comments} field de-localized and sent
to the player to help them figure out what happened.

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

@node Verb Record Structure
@section Verb Record Structure

Please note that this first section is largely not something you need
to use: the @code{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 @code{verbs} attribute.  The @code{verbs}
record has features for each language that the object has verbs on, like
so:

@example
verb: allVerbs(
    en: <verb records>
    lb: <verb records>
)
@end example

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:

@example
en: verbs(
    help: <verb record>
    languages: <verb record>
)
@end example

Each actual verb record contains the language the verb was called
in@footnote{Yes, this is redundant, but there are parts of the internal
code that only get to see the verb record, not the entire @code{verbs}
structure}, and the parsing structure:


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

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


@subsection 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 @code{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.

@emph{Important}: the label of the individual parse records, such as
helpVerbParseName above, @emph{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 @code{parses} list
is as follows: the @code{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:
@example
help: verb(
    language: en
    parses: [
	playerHelpVerb(
	    method: helpVerb
	    endOfInput: nil
	)
    ]
)
@end example
the first, and only, parsing directive is endOfInput, which sees if the
end of the user input has been reached@footnote{this is equivalent to the end of
the line entered by the user at this time}.  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:
@example
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
                )
            )
        )
    ]
)
@end example
which matches either the word languages, then end of input, @emph{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, @code{matchWord} has a feature, @code{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 @emph{cannot} be lists, the must be single
records, and they should not include a @code{method} feature.

@subsubsection Parsing Directives

@multitable @columnfractions .2 .2 .6
@item Directive Name
@tab Arguments
@tab Effect

@item endOfInput
@tab nil
@tab Matches end of character input.

@item string
@tab any 1 atom
@tab 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 @code{Char.isGraph} returns true for.
Because of this, @code{string} pretty much always matches the entire
rest of the line. So, for example, "string: inputString" will pass the
argument @code{inputString} to the verb's method containing the rest of
the line.

@item stringUntil
@tab @code{until} @code{string} @code{rest}
@tab Fills @code{string} with words until it reaches a word that
matches the word (or @emph{list} of words) stored in @code{until}.

@item matchWord
@tab @code{word} @code{rest}
@tab The @code{word} argument should contain a string with the word that
needs to be matched in the input.  @code{rest} contains a full parse
tree.

@item getWord
@tab @code{word} @code{rest}
@tab The @code{word} is filled with the next word in the input.
@code{rest} contains a full parse tree.

@item plus
@tab @code{first} @code{second}
@tab This is the choice operator.  Evaluates @code{first} as a full
parse tree.  If the parsing of @code{first} succeeds, returns that.
Otherwise, tries to parse with @code{second}, returning that if
succesful.  Otherwise fails.

@item multiMatchWord
@tab @code{words} @code{wordFound} @code{rest}
@tab Attempts to match anything from the list of strings in
@code{words}.  Whichever word is actually matched is given to the method
in the atom named by @code{wordFound}.  @code{rest} is the parse tree
for everything after that word.

@item article
@tab @code{wordFound} @code{rest}
@tab Same as multiMatchWord with @code{words} set to the contents of the 
@code{articles} attribute on the Parser object.

@item mayHaveArticle
@tab @code{wordFound} @code{rest}
@tab Same as article, but accepts strings that @emph{don't} start
with an article as well.

@item bracket
@tab @code{left} @code{right} @code{rest}
@tab Matches anything entirely inside the brackets defined by
@code{left} and @code{right}.  Works if both @code{left} and @code{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 @code{left} and the last matches
@code{right}, regardless of what's in the middle.


@end multitable

@node Core Classes
@chapter Core Classes

@menu
@c Deprecated; this just repeats the information in the player's
@c guide way too much, and there's nothing special about verb
@c methods that a programmer can't get from the source anyways,
@c since it's not like one object is going to call another object's
@c verb methods directly.  It shouldn't, anyways.  8P
@c
@c * Core Verbs::		Information about the verbs on the various
@c 			major classes.

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

@node Core Methods
@section 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 @emph{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::
@end menu

@node MozBase Methods
@subsection MozBase Methods

@defmethod MozBase init ozName storageRef serverRef languageStringsObjectRef
Initializes the attributes @var{storageRef}, @var{serverRef} and
@var{languageStringsObjectRef} and the feature @var{ozName} to the
values passed.
@end defmethod

@defmethod MozBase start
None
Does nothing; here to be over-ridden in other classes.
@end defmethod

@defmethod MozBase stop
None
Does nothing; here to be over-ridden in other classes.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod 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. 
@var{convert} is the procedure to convert stored attributes of type
@var{objectRef} into something useful, gotten from the @var{Storage}
object.  @var{objectRef} is used to return an object reference to the
newly initialized object, with all capabilities.
@end defmethod

@defmethod MozBase revoke method capability newCapability
Revokes the current capability on the given method, assuming that
the argument @var{capability} matches it.  The new capability on that
method is returned in @var{newCapability}.
@end defmethod

@defmethod 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).
@end defmethod

@defmethod MozBase setHasProperName hasProperName
Sets the @code{hasProperName} to true or false.
@end defmethod

@defmethod 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.
@table @var
@item language
    The language the verb applies in.

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

@item 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.
@end table
@end defmethod

@defmethod MozBase getName name 
Standard variable get.
@end defmethod

@defmethod MozBase getArticledName name
Returns the object's name with the appropriate article in front of
it.
@end defmethod

@defmethod MozBase getArticledStarterName name
Like getArticledName, but adjusts for the article being the first
word of a sentence if a language requires that.
@end defmethod

@defmethod MozBase setName name 
Standard variable set.
@end defmethod

@defmethod MozBase getVerbs verbs 
Standard variable get.
@end defmethod

@defmethod MozBase deLocalize inputString outputString language

Returns a bare string from a localized string, based on a
language argument.

Arguments:
@table @var
@item inputString
    The string to be de-localized, in string( lang: <string> )
    format as usual.

@item outputString
    A normal Oz string.

@item language
    Optional, the language to de-localize into.
@end table

@end defmethod

@defmethod 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:
@table @var
@item 1.0
    A perfect string match, including case.

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

@end table

@end defmethod

@defmethod 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).
@end defmethod

@defmethod MozBase enhanceStorage storageRef
Adds the capabilities on the given @var{storageRef} to the object's
current capability set for the Storage object.
@end defmethod

@defmethod MozBase selfReference selfRef
Returns a complete reference for the current object, including all
capabilities.  @emph{Very insecure!}
@end defmethod

@defmethod MozBase publicSelfReference selfRef
Returns a complete reference for the current object, with
capabilities for only the methods in publicMethods.
@end defmethod

@defmethod MozBase printedList stringList string
Takes the list of strings in @code{stringList} and concatenates them
together as might be expected in a natural language string (i.e. in
English, using commas and "and").
@end defmethod

@defmethod MozBase printedObjectList objectList string
Like printedList, but the list is a list of object references, from
which names are extracted.
@end defmethod

@node Storage Methods
@subsection Storage Methods

@defmethod Storage start args modules serverObjFileNum realStart newMoz
Extracts command line arguments from @var{args}, sets up links to
external Oz modules, and if @var{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.

@var{newMoz} is used to tell the method that this is the
initialization of a completely new moz.
@end defmethod

@defmethod Storage sync None
Syncs all MOZ objects to disk.
@end defmethod

@defmethod Storage stop None
Saves all MOZ objects to disk.
@end defmethod

@defmethod Storage info None
Outputs debugging information; currently all commented out.
@end defmethod

@defmethod Storage init ozName fileNumToOzName storageRef languageStringsObjectRef
Initializes a new Storage object, mostly using MozBase,init.
@var{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.
@end defmethod

@defmethod Storage loadClasses None
Compiles and loads all the MOZ's .class files.
@end defmethod

@defmethod 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
@var{objectRef}.
@end defmethod

@defmethod Storage saveObject objectWrapper ozName
This method saves the object information to disk.  Note that
@var{objectWrapper} is just the Active Object wrapper, @emph{not} the
standard object reference object.
@end defmethod

@defmethod Storage createObject className objectRef ozName init
Creates an object, returning a standard object reference in
@var{objectRef}.
@end defmethod

@defmethod Storage getClass className class
Returns the class code for the given @var{className}
@end defmethod

@defmethod Storage upgradeObject objectRef className newObjectRef
Upgrades the given object to the given class, returning
@var{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.
@end defmethod

@defmethod Storage getObjectFileNum objectRef fileNum
Take an object reference record and returns the file number
associated with that object reference.  Not for general use!
@end defmethod

@defmethod Storage getServerObjFileNum serverObjFileNum
Returns the file number for the Server object.  Not for general
use!
@end defmethod

@defmethod Storage setServerObjFileNum serverObjFileNum
Sets the file number for the Server object.  Not for general use!
@end defmethod

@defmethod Storage getObjectFromFileNum fileNum objectRef
Retrieves an object given the file number it is stored in.  Not for
general use!
@end defmethod

@defmethod 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.
@end defmethod

@defmethod Storage logLevel level
Set the current logging level to @var{level}.  Logging levels are,
in order from most to least verbose, @var{debug}, @var{info},
@var{warn}, @var{error}, and @var{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.
@end defmethod

@defmethod Storage getConnectionModule module
Returns a copy of the Connection module.  That's the Oz Connection
module, @emph{NOT} the MOZ Connection @emph{class}.  Used by the
Gate and Terminus classes.
@end defmethod

@defmethod Storage getPickleResult url pickleResult
Treats @code{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.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod Storage getCapabilitiesFromOzName ozName capabilities
Returns a full set of capabilities for the object associated with
the @var{ozName} given.
@end defmethod

@defmethod Storage getObjectFromOzName ozName objectRef
Returns an object refrence, including a full set of capabilities,
for the object associated with the @var{ozName} given.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod Storage upgradeObject objectRef className
Forces an upgrade of the object in question.
@end defmethod

@defmethod 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).
@end defmethod

@defmethod Storage createClass className controlRef result
Creates a ClassControl object for the given @code{className}, after
checking that no such class already exists, and returns a reference
to the new object in @code{controlRef}.
@end defmethod

@defmethod Storage writeClassFile className string result
Writes the class file associated with the given @code{className}
using the @code{string} given as the @emph{entire} text of the class
file.
@end defmethod

@defmethod Storage loadClass className
Recompiles the class named @code{className}.  Not that the actual
compilation is threaded off.
@end defmethod




@node Server Methods
@subsection Server Methods

@defmethod Server init ozName storageRef languageStringsObjectRef storageObjectRef startRoom
As per usual, except for @var{storageObjectRef}, which passes extra,
better capabilities to the Server object, and @var{startRoom}, which
passes and object reference to the player starting room.
@end defmethod

@defmethod Server start args modules hold @var{realStart}
As with Storage, except @var{hold}, which returns a variable that
remains unbound until the server is shut down.

@var{realStart} is used to say that this is the real start call,
rather then the normal one that happens when the object is created.
@end defmethod

@defmethod Server stop
Stops the server; also binds @var{hold} from the @code{start} method.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod Server upgradeStorage newClass convert
Storage calls this to get the server to upgrade it during an
@var{upgradeAll} call.  No user servicable parts inside.
@end defmethod

@defmethod Server changePassword player oldPassword newPassword
If the stored password for the login name @var{player} matches
@var{oldPassword}, changes it to @var{newPassword}.
@end defmethod


@node Connection Methods
@subsection Connection Methods

@defmethod Connection start socket storageRef modules parser outputStream
Handles the connection, reading from the TCP/IP port and passing
to the parser, and then back.
@end defmethod



@node LanguageStrings Methods
@subsection LanguageStrings Methods

@defmethod LanguageStrings init ozName storageRef
Nothing unusual here.
@end defmethod

@defmethod LanguageStrings getLanguageString key string
Simple dictionary lookup on the @var{languageStrings} dictionary.
If the @var{key} passed as an argument does not exist, a blank,
globally localized string is returned.
)"
@end defmethod

@defmethod LanguageStrings setLanguageString key string
Dictionary write on the @var{languageStrings} dictionary.  Any
languages not covered by the @var{string} argument are left as they
were.
@end defmethod

@defmethod 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.
@end defmethod


@node Parser Methods
@subsection Parser Methods

@defmethod Parser start storageRef modules outputPort serverStop player languageStringsObjectRef
Starts a new parser objcet.  @var{outputPort} is the Socket object that is used
for sending output to the player.  @var{player} is an object reference
to the player object.
@end defmethod

@defmethod Parser parseOutVerb string result 
Just extracts the first word from the input string, which is then
treated as the verb word.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod 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 @emph{not} implement the verb record parsing strategy;
it calls verbParseRest for that.

@var{verb} contains the verb word, @var{rest} contains the rest of the
input, and @var{matched} is set to true if a match was found.
@end defmethod

@defmethod 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.

@table @var
@item verbParse
    The parse record for the verb.

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

@item result
    The results of the parse, as a record named after the verb word with
features named according to the parse record.
@end table
@end defmethod

@defmethod Parser eval input 
Evaluates the input as a piece of Oz code.  @footnote{Currently isn't
implemented as a verb; this needs to be fixed.}
@end defmethod




@node Described Methods
@subsection Described Methods

@defmethod Described init ozName storageRef name description
Adds name and description attributes to the standard init.
@end defmethod

@defmethod Described getDescription description 
Standard variable get.
@end defmethod

@defmethod Described setDescription description 
Standard variable set.
@end defmethod

@defmethod 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.
@end defmethod


@node Located Methods
@subsection Located Methods

@defmethod Located init location
Adds location to Described's list.
@end defmethod

@defmethod Located getLocation location
Standard variable get.
@end defmethod




@node Mobile Methods
@subsection Mobile Methods

@defmethod Mobile setLocation location
Standard variable set.
@end defmethod






@node Location Methods
@subsection Location Methods

@defmethod Location init contents
Adds contents information to Described's list.
@end defmethod

@defmethod Location addToContents objectRef
Adds the given object to the current @var{contents} list.
@end defmethod

@defmethod Location getContents contents
Standard variable get.
@end defmethod

@defmethod Location getContentsString string
Returns a string that contains a list of the names of all the objects in the
object's @var{contents} list.
@end defmethod

@defmethod Location removeFromContents objectRef
Removes the given object from the current @var{contents} list.
@end defmethod

@anchor{location-wantToGet}
@defmethod Location wantToGet newLocation origRecord newRecord
This is called by other objects who desire to get one of the objects
from our @var{contents} list.  @xref{location-get, , @var{get} on Location}.
@var{origRecord} is a minimal object reference to the object that
@var{newLocation} wants.
@end defmethod

@anchor{location-wantToGive}
@defmethod Location wantToGive oldLocation objectRef result
This is called by other objects who desire to give us one of the objects
from their @var{contents} list.  
@xref{location-give, , @var{give} on Location}.  @var{result} is set
to true if we accept the object, false otherwise.
@end defmethod

@defmethod Location searchByObjectName name except objectRef result language
Returns the object in our contents best matching the given name, else returns
a standard result in @code{result}.  @code{except} is used to
exclude the calling object from the searching, as this will cause a
hang.
@end defmethod

@defmethod 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 @code{except} argument takes an object reference and causes the
string to @emph{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 @code{except} argument!
@end defmethod

@anchor{location-get}
@defmethod 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 @var{objectRef} is limited reference to the object we want to
@emph{get}.

@xref{location-wantToGet, , @var{wantToGet} on Location}.
@end defmethod

@anchor{location-give}
@defmethod 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.
@xref{location-wantToGive, , @var{wantToGive} on Location}.
@end defmethod




@node Container Methods
@subsection Container Methods

@defmethod Container init
Merges the @var{init}s of Location and Thing; Location's @var{init} is
run first.
@end defmethod



@node Player Methods
@subsection Player Methods

@defmethod Player init
Runs the @var{init} methods for Location and Mobile (in that order).
Sets @var{language} and @var{outputPort} to nil.
@end defmethod

@defmethod Player start modules outputPort realStart
Sets the @var{outputPort} object variable.

@var{realStart} is used to say that this is the real start call,
rather then the normal one that happens when the object is created.
@end defmethod

@defmethod Player stop
Nothing special here, except during upgrades.
@end defmethod

@defmethod Player setStorage storage
Just used to set the storage attribute with a new capability set.
Used for wizardry and dewizardry and the like.
@end defmethod

@defmethod 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.
@end defmethod

@defmethod Player setLanguage language 
Standard variable set.
@end defmethod

@defmethod Player getLanguage language 
Standard variable get.
@end defmethod

@defmethod Player setStorage storageRef
Standard variable set, for storageRef.
@end defmethod

@defmethod Player grabInputUntil untilString inputString result
Takes all input entered by the player until the player types the
string passed in @code{untilString}.  The input is returned in
@code{inputString}.  @code{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.
@end defmethod

@node Exit Methods
@subsection Exit Methods

@defmethod Exit setDestination destination
Sets the destination for this exit to the object given.
@end defmethod

@defmethod Exit setName name
Sets the exit's name.  Also creates verbs corresponding to the new
name, so the player can use the exit.
@end defmethod



@node Gate Methods
@subsection Gate Methods

@defmethod Gate setDestination destination
Sets the destination for this exit to the object referenced by the
pickle stored at given url.
@end defmethod



@node Terminus Methods
@subsection Terminus Methods

@defmethod Terminus getTicket ticket
Uses the Connection module to return a ticket to itself.
@end defmethod

@defmethod Terminus writeTicket file
Uses the @code{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).
@end defmethod



@node Control Methods
@subsection Control Methods

@defmethod 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 @code{name} attribute.
@end defmethod

@defmethod Control selfMatch
Makes sure that its name is set properly, based on the current name
of the controlled object, then runs the normal @code{selfMatch} method.
@end defmethod

@defmethod Control otherwise
The @code{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.
@end defmethod

@defmethod Control getMethodList methodList
Returns the combined methods of the Control object and the
controlled object.
@end defmethod

@defmethod Control getVerbs verbs
Returns getControlVerbs on the underlying object.
@end defmethod

@defmethod 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 @code{name}.
@end defmethod

@defmethod Control publicSelfReference
Calls selfReference: with Control objects, possession is ten tenths
of the law.
@end defmethod

@node ClassControl Methods
@subsection ClassControl Methods

@defmethod ControlClass getName name
Generates a name based on the name of the underlying controlled
class. Also updates the Control object's @code{name} attribute.
@end defmethod

@defmethod ControlClass selfMatch
Makes sure that its name is set properly, based on the current name
of the controlled object, then runs the normal @code{selfMatch} method.
@end defmethod



@node Unsorted
@chapter Unsorted

@itemize @bullet

@item 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.

@item Add objectName or whatever to the verb record info.
@item Example verb creation, including the method.
@item Examples of 'fun' objects (meep, wind-up ducky, tame falcon).

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

@item Put a list of articles somewhere.

@item Document the standard arguments to verb methods.

@item 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).

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

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

@end itemize

@node Command Index
@chapter Command Index

@printindex vr

@node Method Index
@chapter Method Index

@printindex fn


@bye
