LPC MANUAL --- SEARCHING
========================

Contents:

    1. introduction
    2. implementation

1. INTRODUCTION
===============

This manual is about adding the ability to search an object. Basically making
something searcheable is a two stage rocket. First you have to identify that
it can be searched and then you have to handle the actual searching. Searching
basically takes two forms:
    search <x>
    search <x> for <y>

The search command in the player soul will call the search_object(string str)
routine in the object that will make the player wait for a while during the
execution of the search. In theory this means that search_object() could be
masked, but we do not suggest people to do this.

2. IMPLEMENTATION
=================

To make an item searcheable, add the property OBJ_S_SEARCH_FUN to the item.
As value, give it the string value with the name of the routine that you have
defined in the object, e.g. "my_search_fun".

    add_prop(OBJ_S_SEARCH_FUN, "my_search_fun");

Then you define the routine string my_search_fun(object player, string str) to
handle the actual searching. Example:

    string
    my_search_fun(object player, string str)
    {
        /* Searching this item simply reveals a bit of extra info. */
        return "Close examination of " + LANG_THESHORT(this_object()) +
            " shows that some letters are carved into the bottom.\n";
    }

The 'player' obviously is the searching player and 'str' will be the text that
is being searched. Note this can be of the form "<x> for <y>". If you simply
want to react on any searching of your item, then you can ignore the 'str'
argument and do what you want to do when the player searches your object.

The routine "my_search_fun" has to return a string that will be printed to the
player, or 0 to indicate that the search failed.

    "text" - the "text" will be printed to the player to inform him of the
             result of the search (whether it is good or bad).
    ""     - no text will be printed to the player. This assumes that you have
             taken care of the message within your routine.
    0      - the search failed. A default fail message will be printed.