CPDEE - MOO Help Contents - Core Utility Help Topics (#22) - N

===== help $no_one ===============================

..is a powerless player. He owns no objects, not even himself; nor does he own any verbs. He is, however, a programmer and thus may use eval(). In fact his sole purpose is to evaluate questionable code. `questionable' could be in either or both of the following senses (1) Its origin is sufficiently uncertain so that there is no obvious way of deciding whose permissions it should run under. (2) The code itself is potentially malicious, i.e., to the extent that one does not want to be evaluating it using one's own permissions. set_task_perms($no_one); is thus the canonical idiom in wizard code for rendering anything that follows mostly harmless. For use by ordinary programmers, we have: $no_one:eval(string) which attempts to evaluate an arbitrary string using $no_one's permissions. string is either an expression or ";" followed by one or more statements, of which the final semicolon may be omitted. return values are what eval() would return (either {1,value} or {0,@error_messages}).

===== help object-matching==========================

Which :match...() Verb Do I Call?

There are many situations where one wishes to obtain an object from a room or a player's .contents whose name/aliases matches a particular string. There are four main verbs available for this and it is important to understand the distinctions between them and how they are supposed to be used.

(*)  LOC:match("X")
     -- what you get looking for something that is inside LOC and named "X".
        By default, this looks through LOC.contents to find a unique object 
        having a name or alias that has "X" as a prefix.

Essentially, you can think of :match as a contents-matching verb, though, e.g., for rooms you also get matches on exits as well.

(*)  LOC:match_object("X", YOU)           [YOU defaults to player]
(*)  YOU:my_match_object("X", LOC)        [LOC defaults to player.location]
     -- what YOU get being located at LOC and looking for something named "X".
        By default these both return $string_utils:match_object("X",LOC,YOU)

(*)  $string_utils:match_object("X", LOC, YOU) 
   -- what you *would* get *if* YOU were a typical player, YOU were inside LOC,
      YOU were looking for something named "X", *and* LOC were a typical place.

In other words, $string_utils:match_object describes the :match_object() algorithm for "typical places" and the :my_match_object for "typical players":

    (1)  check for "X" being one of "", "me", "here", "$something", or "#n"
    (2)  try YOU:match("X") i.e., something in your inventory (maybe)
    (3)  try LOC:match("X") i.e., some object in the room (maybe)

The distinction between these location:match_object and player:my_match_object has to do with whether the player or the location should determine what the matching algorithm is. Which one you should use depends on the command that you are writing. If you are writing a command with a virtual-reality flavor, then you should be respecting the room owner's idea of which objects you can "see" and thus the command should be calling the location's :match_object verb. If you are writing a building/programming command where it is appropriate for the player to determine the matching algorithm --- whether because the current location is irrelevant, not to be trusted, or both --- then the player's :my_match_object verb should be called.

Examples:

  `look diamond in box'
      calls box:match("diamond").  This is a match on the contents of box.

  `take ball', 
      calls player.location:match_object("ball")
      to determine which "ball" to take.  Note that if the room is dark, 
      we might not be able to find any "ball".

  `@program widget:foo', 
      calls player:my_match_object("widget") to get the player's own idea
      of what "widget" should be.  Note that if I were carrying something 
	        named "widget" and expecting to be programming a :foo() verb on it,
      it would be potentially disastrous should the room where I am decide
      for me to be programming something else (not even necessarily 
      called "widget").

Object Matching Failures

As with other matching routines, one gets back

  $failed_match in the case of no matching object
  $ambiguous_match in the case of more than one matching object
  $nothing in the case of a blank string argument

or an object-id. In these first 3 cases, one usually wants to translate these nonresults to the player; this is what
$command_utils:object_match_failed.
The standard idiom to mimic what the builtin parser does, say, with the direct object is

  dobj = foo:match_???(dobjstr);
  if($command_utils:object_match_failed(dobj, dobjstr))
    "...give up.  nothing to do.   error message has already printed...";
  else
    "...dobj is something useful.  Continue...";
    ...
  endif

===== help $player_db =============================

Database of Players

This is an instance of the Generic Database ($generic_db) that holds the {name/alias,#objectid} pairs for every name and alias of every player in the MOO.

Verbs supplied include

  :find(string)        => player or $ambiguous_match or $failed_match
  :find_exact(string)  => player or $failed_match (does not do partial matches)
  :find_all(string)    => list of all matching players

  :insert(string,player) 
       records that string is now a name or alias of player
  :delete(string) 
       removes string from the db
  :available(string)
       returns 1 if string is available as a player name or alias,
       an object if string is in use, or 0 if string is otherwise unavailable.
  :load()
       resets the db, inserting all current player names and aliases.

The internal representation and all of the above verbs (except :load() and :available()) are as described for $generic_db. It should be noted that for any application that involves resolving a player name from a command line, you should be using $string_utils:match_player() rather than $player_db:find(), since the former will deal correctly with other ways of referring to players apart from their names and aliases (e.g., literal object numbers, "me", "$no_one"...). :load() needs to be done periodically as it is possible for the player db to get out of synch with reality. In particular, there is currently no way to block someone writing his own player :recycle() verb that neglects to remove his names from the player db.

While a :load() is in progress the .frozen property is set to 1 to indicate that any results of :find*() are not to be trusted.

===== help receiving-mail===========================

Receiving Mail

By definition a recipient "receives" a mail message when its :receive_message verb is called with that message as an argument.

:new_message_num() => number that will be assigned to the next incoming message. By default this returns the maximum of the message numbers appearing in messages or .messages_going, incremented by 1. If the recipient is a player then the value returned will be 1 higher if it conflicts with the player's current message number for him/herself.

:receive_message(msg,sender) By default this first calls this:new_message_num to obtain a message number to assign to the incoming message and then appends {num,msg} to this.messages. `sender', the original sender, is supplied in case one wants different action depending on who is sending the message (e.g., mail-gagging). The return value should be an error or string if :receive_message is considered to have failed in some way. Otherwise, a number should be returned --- this number is given to any :notify_mail routines that are called and is expected to either be 0 or the number assigned to the incoming essage.

Note that :receive_message can do arbitrary things, including resending the same message to a new destination. Hacking :receive_message to resend messages is different from using .mail_forward in the following respects (1) the resent message is considered to be a distinct message having this object as its "author" --- i.e., the From: line will necessarily be different. (2) since this "forwarding" is invisible to the mailsystem, there is no protection against loops and multiple copies.

===== help $recycler==============================

Rather than having the server built-in recycle() and create() functions handle the creation and destruction of objects, a recycling center has been created to simulate these actions by changing objects that would have been recycled into children of $garbage (The Generic Garbage Object) and making them owned by Hacker, and then when they're needed again, to avoid a raw create() command, those objects are given to whoever's asking for them. Most Useful Verbs $recycler:_recycle( object ) This will effectively recycle an object. (As a point of fact, it changes ownership of the object to Hacker and makes the object a child of $garbage.) It handles .ownership_quota and .owned_objects properly. Generally, use this instead of a recycle() in your verbs. $recycler:_create( parent object [ , new owner object ] ) This effectively creates an object (with the specified parent, if possible, and with the specified owner, if possible; these are the same restrictions as on the server create() builtin). This is what should generally be used instead of create() in your programming. $recycler:valid ( object ) This is a variant of the server built-in valid() except that it handles the $garbage objects as well. It returns a 1 if the object specified -is- valid and is -not- a $garbage object. Other Notes request <object> from <recycler> This is not an internal verb (it's !x). It is, however, a command-line verb that can be used to request a specific object from the recycler. It's also useful for the creation of objects like a Magic Number Repository. When the object is removed from the recycler, the .announce_removal_msg is announced to the room if it's set (it's piped through $string_utils for pronoun substitution). show-history <recycler> This is a wizardly verb which allows wizards to check the `history list' of the recycler. The history maintains the latest ($recycler.nhist) entries.

$recycler.orphans This maintains a list of objects for which the recreation process got mangled. It ought to be checked every once in a while to see what's up.

===== help $room================================

The Generic Room ($room)

(1) Announcements

:announce         (@text)         => broadcasts to all except player
:announce_all     (@text)         => broadcasts to all
:announce_all_but (objects,@text) => broadcasts to all except those in objects

say, emote (2) Command recovery :huh (verb,args) - server hook: last chance to make sense of verb :here_huh (verb,args) - room's last attempt to parse something :here_explain_syntax (this,verb,args) - attempts to explain usage of verb (3) Residency free_home - true => @sethome allows anyone to set his .home to be here residents - objects on this list may teleport in and/or set their homes here. :accept_for_abode(player) => true iff player should be allowed to set .home to this room. @resident*s (4) Looking dark - true => contents are not visible ctype - 1..4 for four different styles of .contents lists :match (string) => exit or object in room's .contents :tell_contents (objects,ctype) - format objects according to ctype, tell player l*ook (5) Entrance and exit. :accept (object) - Called by move() and :moveto() before an object enters a room, if false is returned, movement is prevented. Protocol permits this verb to make noise (though this is discouraged) as this is the only place the room will learn the object's original location. :acceptable (object) - Called by verbs which wish to check whether movement will be possible. Protocol prohibits this verb from making noise and requires it to return the same value as :accept would for the same arguments. :is_unlocked_for (object) - interface with the @lock protocol. Returns true or false depending on the state of locks for the object with the room. Other things may prevent entrance even if this returns true. Protocol prohibits this verb from making noise. :enterfunc (object) - called after entrance has succeeded. Noise is fine. :exitfunc (object) - called after an object has successfully left. Noisemaking is fine. (6) Topology and Movement via Exits See `help $exit' for an explanation of how the generic $exit works. free_entry - true => `teleporting' in is allowed false => only residents may teleport in exits - list of invokable exits leading from this room entrances - list of recognized exits leading to this room blessed_object - object currently entering via an exit blessed_task - task_id for entering object :match_exit (string) => exit whose name matches string :bless_for_entry (object) - set up room to accept object arriving from entrance :add_exit (exit) :add_entrance (exit) :remove_exit (exit) :remove_entrance (exit) e/east/w/west/s/south/n/north/ne/northeast/nw/northwest/se/southeast/sw/southwe st/u/up/d/down, go, @add-exit, @add-entrance, @remove-exit, @remove-entrance, @exits, @entrances (7) Ejection victim_ejection_msg/oejection_msg/ejection_msg :*_msg() messages @eject S

===== help sending-mail============================

Sending Mail

$mail_agent:send_message(from,recipients,headers,body)
  from:        sender of the message 
               (this must be you or something you own; otherwise => E_PERM)
  recipients:  object or list of objects (must all be players or 
               $mail_recipient descendants)
  headers:     either a string (contents of the Subject: line) 
               or a list {subject,replytos} replytos is a list 
               of objects designated to receive replies.
               Use {"",replytos} to have a Reply-to: without a Subject:

This is the canonical way to send a mail message from a program. This calls $mail_agent:make_message to format the arguments into an actual message (see `help mail-format') and then $mail_agent:raw_send to do the actual sending which goes as follows: (1) Call :mail_forward on all recipients add any new recipients thus obtained to final recipient list, keep calling mail:forward on the new recipients until we obtain no additional recipients. If one of the initial recipients is invalid, is not a player or $mail_recipient, or has its mail_forward return a string error, then we print the error message and abort at this point with no mail being sent. If one of the later recipients bombs similarly, error messages are printed, but in this case mail still goes out to the other recipients. (2) Call :mail_notify on all recipients encountered in stage (1) to get a list of objects to notify. (3) All final recipients receive the message (see `help receive-mail') (4) All notifications are delivered (using :notify_mail())

We return {0, @failed_recipients} if we bombed out at step 1. Otherwise return {1, @actual_rcpts} indicating what mail was sent.