When a player types help, the following list of objects is consulted for .help properties: the player itself, all ancestors of player up to and including $player, and, if the current location is a room, the current location together with all ancestors of the current location back to and including $room. Each help property should have as value either an object or a list of objects (otherwise we just ignore it). These objects are then strung together as a list of `help databases' to be searched in order for the requested topic.

A help database (in the sense of anything that is usable by $player:help()) is any object having the following three verbs:

:find_topics([string])
where string is a supposed help topic, returns a list of strings, i.e., actual help topics that this db knows about, or some boolean false value in the event that this db is clueless... If no arguments are given, this should return a list of all topics in the db

:get_topic(string)
given one of the strings returned by :find_topics this either returns a list of strings (text to be spewed to the player) or returns 1 to indicate that it has already taken care of printing information to the player.

:dump_topic(string)
like get_topic, but instead returns the raw text of a help topic as a (download/upload) script

In short if :find_topic reports that a particular db knows about a given topicit returns the full topic name, so that :get_topic may be called on it later. :dump_topic is used by maintainers (see $wiz:@gethelp) to edit help topics.

$generic_help and $help

The Generic Help Database, $generic_help, is the parent class of a particular kind of help database of which $help is an instance. On help databases of this type, every help topic has a corresponding property, interpreted as follows:

this.(topic) = string
one-line help text.

this.(topic) = {"*<verb>*",@args}
call this:<verb>(args,dblist) to get text where dblist is the list of help objects that would have been consulted had the topic not been found on this object.

this.(topic) = other list of strings
multi-line help text

For the {"*<verb>*",...} form, the current verbs available are

{"*forward*", topic, @rest}
- get help text for topic and then append the lines of `rest'. rest may, in turn, begin with a "*<verb>*"...

{"*pass*", topic, @rest}
- get help text for topic from the first help database after this one that actually has help text for topic, and then append lines of `rest'. As with "*forward*" rest may, in turn, begin with a "*<verb>*"...

{"*subst*", @lines}
- All occurences of %[exp] in lines are replaced with the value of exp which is assumed to evaluate to a string. All lines beginning with %;exp are replaced with the value of exp which is assumed to evaluate to a list of strings. Evaluation is done using $no_one's permissions so exp in either case can only refer to public information.

{"*index*", title}
- returns a list of all topics in this database, arranged in columns. title is used as a heading for this index.

{"*objectdoc*", object}
- gets the documentation for the given object (i.e., object:help_msg()) N.B. as with all other *verb* arguments, object must be a string.

{"*verbdoc*", object, verbname}
- gets the documentation for the named verb on the given object (i.e., any strings at the beginning of said verbcode) Individual help dbs are free to define additional verbs that may be used in this context. $help itself defines the following additional such verbs:

{"*index_list*"}
- returns a list of all index topics in all databases in the search list. An index topic is one whose actual text is {"*index*", something}. When creating a help db, you should be sure to make an index topic.

{"*full_index*"}
- prints indices for all help databases in the search list.

To indicate what objects should be cleaned:

:add_cleanup(object[, requestor[, where]])
Ask the housekeeper to clean 'object' for 'requestor' to 'where'. Requestor defaults to 'player'. Where defaults to object.location.

:remove_cleanup(what[, requestor])
Remove 'what' from the cleanup list at 'requestor's request. Will remove it only if 'requestor' made the original request and owns the object or the destination.

To actually get the housekeeper to clean stuff up:

:cleanup([insist])
Clean up player's objects. Argument is 'up' or 'up!' for manually requested cleanups. 'up!' means to clean things even if it's against the housekeeper's better judgement.

:replace(object[, insist])
Clean up the indicated object. 'insist' is as in :cleanup.

:continuous()
Starts the housekeeper cleaning continuously, killing any previous continuous task. This should be called only when starting up a new MOO, or if something has gone wrong, as normally it will just keep going without any help.

:litterbug()
Clean up all the places in housekeeper.public_places by getting rid of all contents not in their .residents lists. This is called by :continuous, so it doesn't need to be called directly.

To find out what's being cleaned to where for whom:

:cleanup_list([whom])
Show 'player' the personal cleanup list for 'whom', or the housekeeper's complete list if no argument is given.

COMMANDS FOR UNCONNECTED PLAYERS

Recall that for each line that an unconnected player types, the server parses that line into words (the same way normal commands are parsed into a list of words that is then assigned to `args') and then #0:do_login_command is called.

:parse_command (@args) => {verb, @args}
given the sequence of arguments that were fed to #0:do_login_command this returns the name of a verb on $login to be called together with a list of arguments to be passed to it.

By default this just returns args iff args[1] names an actual verb on $login that is +x and has args {"any","none","any"}. Otherwise, it returns one of

  .blank_command   -- verb to call if command line is empty
  .bogus_command   -- verb to call if command line otherwise unintelligible

Currently the following verbs are availabe to non-connected players

  h*elp @h*elp       -- print .welcome_message
  ?                  -- print a short list of available commands
  w*ho @w*ho         -- print a list of logged in players (excluding wizards)
  co*nnect @co*nnect -- connect to an existing player
  cr*eate @cr*eate   -- create a new player
  up*time @up*time   -- tell how long the server has been running
  version @version   -- tell which version of the server is running
  q*uit @q*uit       -- logoff

CUSTOMIZATIONS

  .welcome_message 
    -- the message for "help" to print.
  .create_enabled 
    == 0 => @create prints .registration_string if one tries to use it
    == 1 => anyone from a non-blacklisted site (see `help blacklist')
            may use @create to make a new player

  .registration_address
    -- an email address for character creation requests
  .registration_string  
  @more
    -- string to print to players to give them information about how to get 
       a character created for them, .registration_address is substituted 
       for %e, % for %%
  .newt_registration_string
    -- string to print to @newted players (see `help @newt').
       same substitutions as for .registration_string.

:registration_string() => .registration_string with substitutions

:newt_registration_string() => .newt_registration_string with substitutions

:player_creation_enabled(connection)
decides whether someone on connection should be allowed to create a player. If you decide this shouldn't depend strictly on the blacklist and on the value of .create_enabled, here's where the extra code can go.

:check_for_shutdown()
prints a warning message to append to the login banner in the event that the server will be going down soon.

:check_player_db()
prints a warning message to append to the login banner in the event that $player_db is being reloaded to warn players that their character names might not be recognized.

SITE LOCKS

1. utilities for performing basic mailsystem functions, e.g., matching on recipient names, resolving mail forwarding, formatting messages, sending messages

Recipient Matching

match           - match on a $mail_recipient
match_recipient - match on either a $mail_recipient or a player
match_failed    - print angry messages to the user for $failed/ambiguous_match

look_self       - provides a list of available $mail_recipients
check_names
touch
accept

Message Format

make_message        - produces a message in the canonical transmission format
name                - single recipient     => string for address field
name_list           - list of recipients   => string for address field
parse_address_field - address field string => object list

Sending Messages

send_message  - advertised message sending routine.
raw_send      - raw message sending routine 
                (only called by $mail_editor:send and this:send_message)
resolve_addr  - converts a given list recipients into a list of actual 
                recipients and objects to be notified.
sends_to      - Does X forward (transitively) to Y

Mail Options

option         
option_verbose

Ideally, the verbs to perform operations on a given mail recipient would be located on the recipient itself, except for the fact that these verbs also need to be located on players, which for various reasons, shouldn't be children of $mail_recipient. Multiple inheritance would solve our problems, but we don't have it yet. Ergo, both $mail_recipient and $player refer to the following verbs here:

display_seq_full     print entire text of messages  (@read)
display_seq_headers  print headers of messages      (@mail)
rm_message_seq       remove messages                (@rmm)
undo_rmm             undo last rm_message_seq       (@unrmm)
expunge_rmm          flush removed messages         (@unrmm expunge)
list_rmm             list removed messages          (@unrmm list)
renumber             renumber messages              (@renumber)
display_seq_full     print entire text of messages  (@read)
display_seq_headers  print headers of messages      (@mail)
rm_message_seq       remove messages                (@rmm)
undo_rmm             undo last rm_message_seq       (@unrmm)
expunge_rmm          flush removed messages         (@unrmm expunge)
list_rmm             list removed messages          (@unrmm list)
renumber             renumber messages              (@renumber)
msg_summary_line     msg header => display_seq_headers/list_rmm summary line
parse_message_seq    command line msg sequence spec => message sequence
new_message_num      => message number of next new message
length_all_msgs      => number of messages (total)
length_num_le        => number of messages numbered <= some number
length_date_le       => number of messages dated <= some date
exists_num_eq        => true iff there exists a messsage with the given number
from_msg_seq         => message sequence of msgs from given sender(s)
to_msg_seq           => message sequence of msgs to given recipient(s)
subject_msg_seq      => message sequence of msgs with subjects containing text
body_msg_seq         => message sequence of msgs with bodies containing text
messages_in_seq      => list of {message number, message} pairs
messages             == :messages_in_seq(1,:length_all_msgs()+1)   (obsolete)

The "headerlist_len" property is the length of the headers list displayed when someone browses a folder.

.mail_forward 
 -- list of objects that will receive any mail that gets sent to you.
    Objects on this list should either be players or descendants of 
    $mail_recipient.
    If this list is nonempty, you will not receive any mail yourself unless
    you are on it.  E.g., if Rog is #4292 and ur-Rog is #6349

  #6349.mail_forward={}            -- usual case; ur-Rog gets his own mail.
  #6349.mail_forward={#4292}       -- Rog gets ur-Rog's mail instead.
  #6349.mail_forward={#6349,#4292} -- ur-Rog gets mail and Rog gets a copy.
  #6349.mail_forward={#-1}         -- ur-Rog's mail disappears without a trace.

.mail_notify
 -- list of objects to be notified whenever mail is sent to you.
    This list may include anything that has a :notify_mail() verb.
    Notification will take place regardless of whether or how your mail
    is forwarded.  

Thus, in the previous example

  #4292.mail_notify={#6349} --- means that ur-Rog will be told
                                whenever Rog is sent new mail.

.mail_options
 -- this controls lots of miscellaneous things.  Use the @mail-option command
    to view and set these options (see `help @mail-option')

If :mail_forward returns a nonempty list, the recipient itself will *not* actually receive the mail message unless it is included in the list. #-1 is allowed to be on the list; it is ignored but does make the list nonempty. Thus, having :mail_forward() return {#-1} is the canonical way to have arriving mail disappear without being kept or forwarded.

:mail_notify([from])
should return a list of objects that are to be told about any mail sent to this recipient (whether or not the recipient actually receives it).
Said objects must have a :notify_mail verb, but other from that, there is no restriction on what these can be.

    object:notify_mail is called with the arguments 
    (sender,recipients,msgnumbers) where 
      recipients  == list of recipients including object in .mail_notify
      msgsnumbers == corresponding list of :receive_message return values
                 (or 0 if :receive_message is not actually called, which
                  will be the case if the recipient forwards without keeping)

:moderator_forward(from) 
    what :mail_forward should return for mail coming from unapproved senders
    This returns .moderator_forward (pronoun_subbed if a string) by default.

:moderator_notify(from)
    what :mail_notify should return for mail coming from unapproved senders
    This returns .moderator_notify (pronoun_subbed if a string) by default.

It should rarely be necessary to actually modify any of :*_forward/*_notify verbs, since one has a fair amount of control over their behavior via the following properties

  .mail_forward
  .mail_notify
  .moderated          (see `help MR-access')
  .moderator_forward
  .moderator_notify

It is highly recommended that if you are creating custom mail recipients with variable reader/sender lists, i.e., you find you need to write your own :is_readable/usable/writabe_by verbs, you are best off if such verbs are of the form return pass(@args) || << your_test(args[1]) >>

and have .writers == .readers == {} and .moderated == 1.  This will ensure
 (1) wizards having write access
     --- necessary in order for :receive_message to work
 (2) writers being able to read and send (the converse being a ludicrous 
     situation), 
 (3) persons on the mail_forward list of someone with reader access will also
     have read access (convenient).

The .aliases field holds the names by which one may refer to the list, but only those names not containing spaces actually count for anything. As with certain other types of objects (e.g., players), set_aliases() needs to be called in order to change the .aliases field.

$mail_agent:match(name) 
    is the canonical way to obtain the objectid of a mailing list 
    given the name ("*" is assumed; an initial "*" will be dropped).

$mail_agent:match_recipient(name) 
    is the canonical way to obtain the objectid of a list or player
    matching the given name.  An initial "*" indicates that this is 
    supposed to be a list.

$mail_agent:match_failed(objid,name) 
    is the mail_recipient counterpart to $command_utils:object_match_failed

    :add_forward(@new_recipients)
    :delete_forward(@recpients)
    :add_notify(@new_notifiees)
    :delete_notify(@notifiees)