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